安装与前置条件
适用于 Python 3.11+，当前实现版本 0.2.0；包名 skiva-sdk，导入名 skiva_sdk。已发布到 PyPI。以下命令固定安装 0.2.0；升级时显式替换版本号。Windows 激活虚拟环境使用 .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"
使用启用的 Agent Profile 所属客户端凭据，不能使用管理员或登录会话令牌。地址填写服务端地址或反向代理前缀，不包含 /distribution/v1。可信本地环境之外使用 HTTPS。
export SKIVA_SERVER_URL=http://localhost:8080
export SKIVA_CLIENT_TOKEN=your-client-credential
Profile 需要有已发布快照及 Skill 访问权限。SDK 的动态模式仍遵守服务端 Profile 的固定版本配置，不绕过权限。
先在 Agent 接入 创建 Profile 与客户端身份。SDK 直接访问分发 API，不需要 FUSE。
发现与加载
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 包含 SnapshotRef、不可变 Skill 元数据与 catalog_digest。SkillContent 包含实际 ref、目录摘要、清单相对路径、文件摘要和正文。输出包裹结构会转义 XML，但名称和描述仍来自 Skill 发布者；转义不意味着它们可信，更不意味着可以覆盖系统策略。
发现提示词要求模型按相等性比较版本，不比较版本号大小；不一致时重新加载。回滚与向前更新采用相同行为。同一快照下可见文件集合变化也会改变 catalog_digest。这是面向模型的降级提示机制，不保证模型忘记旧指令。
调用 catalog.render() 只生成文本。宿主应用负责把它放入模型请求；使用 Pydantic AI 适配器 可自动接入。