Installation and prerequisites
Requires Python 3.11+. Current implementation: 0.2.0; package: skiva-sdk; import: skiva_sdk. Install from PyPI. These commands pin version 0.2.0; update the version explicitly when upgrading. On Windows activate with .venv\Scripts\Activate.ps1.
python -m venv .venv
source .venv/bin/activate
python -m pip install "skiva-sdk==0.2.0"
# Pydantic AI adapter (2.59.0)
python -m pip install "skiva-sdk[pydantic-ai]==0.2.0"
Use a client credential assigned to an enabled Agent Profile, not an admin/API session token. Use the server origin (or reverse-proxy prefix), without /distribution/v1. Use HTTPS outside a trusted local environment.
export SKIVA_SERVER_URL=http://localhost:8080
export SKIVA_CLIENT_TOKEN=your-client-credential
The profile must have a published snapshot and authorized Skills. SDK dynamic mode respects server-side profile pins; it does not bypass them.
Create a Profile and client identity in Clients and Agents. The SDK talks directly to the distribution API; FUSE is not required.
Discovery and loading
import asyncio
from skiva_sdk import SkivaClient
async def main():
async with SkivaClient.from_env() as client:
async with client.bind() as skills:
catalog = await skills.catalog()
print(catalog.render())
if catalog.skills:
content = await skills.load_skill(
catalog.skills[0].name,
expected_snapshot_id=catalog.ref.snapshot_id,
expected_catalog_digest=catalog.catalog_digest,
)
print(content.render())
asyncio.run(main())
Catalog contains a SnapshotRef, immutable Skill metadata and catalog_digest. SkillContent contains the actual ref, catalog digest, manifest-relative path, file digest and text. Rendered envelopes escape XML markup. Names/descriptions still originate from published Skills: treat publishers as a trust boundary, not as trusted system-policy authors simply because text is escaped.
The discovery prompt tells the model to compare snapshot IDs for equality, not chronological order, and to reload content whose version differs. Rollback is handled the same way as forward updates. catalog_digest also changes when the authorized file set changes within one snapshot. This is a model-facing fallback, not a guarantee that old instructions are forgotten.
Calling catalog.render() only produces text. Your host application must place it in model requests; the Pydantic AI adapter automates that integration.
Continue reading
Snapshots and update policies · Pydantic AI integration · File export and framework integration · SDK reference and testing