需要真实文件时
async with skills.snapshot() as batch:
async with batch.materialize() as directory:
# 将目录交给框架或子进程，子进程必须在退出此代码块前结束。
print(directory)
SDK 在临时目录导出完整私有副本，保留读取和执行权限位，不创建 FUSE 挂载或共享对象的可写硬链接。拒绝不适合支持平台的路径，包括大小写折叠冲突。退出时清理。权限位不能隔离拥有文件的进程。导出后的直接读取绕过 SDK 授权，撤权无法收回导出的字节。 新快照需重新导出，不修改旧目录。
选择接入方式
| 场景 | 方式 | 边界 |
|---|---|---|
| 能控制模型请求与工具 | SDK 目录与加载 API | 宿主负责注入发现列表；Pydantic AI 有现成适配器 |
| 框架要求目录路径 | snapshot().materialize() | 固定副本，退出清理；新版本创建新目录 |
| 不能改造 Agent、只能配置搜索目录 | Linux FUSE | 文件更新不自动替换模型中的 Skill 列表 |
Agno 与 LangChain
当前没有内置 Agno 或 LangChain 适配器。若框架接受本地目录，可传入导出路径，且必须在导出上下文内完成整个任务；这本身不保证框架刷新其 Skill 索引。若希望执行中更新发现列表，需要在框架的模型请求钩子中刷新并注入目录文本，再封装版本校验加载工具。不要把 SDK 的 Pydantic AI 验证结果当作其他框架的兼容性证明。