Pydantic AI Skills
为 Pydantic AI 提供 Agent Skills 支持：渐进式加载技能指令，配合远程注册表与捆绑脚本沙箱执行，让技能库随规模扩展而不撑爆提示词。
证据显示：技能文件工具默认拒绝未加载的技能（测试明确验证拒绝路径）、沙箱staging跳过越界符号链接并告警、避免/tmp工作目录、 SECURITY.md 明确声明'加载不可信技能等同于运行不可信代码'的信任边界。扣分处：默认脚本执行器（LocalSkillScriptExecutor）仍在宿主机上以子进程运行脚本，沙箱为可选extra而非默认；没有面向最终用户的人工确认机制，只有加载门控；注册表同步的回滚/恢复路径无证据。最低权限与外部效应因宿主机默认执行仅得2分；用户确认仅1分；回滚1分。
证据显示：测试覆盖构造期校验错误（harness的ValueError原样透出）、include/exclude拼写错误报错并列出可用技能、缺失optional extra时ImportError指名extra名称、沙箱复用/重建/生命周期的边界情况均有钉死测试。依赖下限（pyyaml 6.0.1、pytest-asyncio 0.23.5等）在CI的test-lowest-versions作业中实测验证。一致性、依赖可用性与错误信息质量均有充分证据支持满分；未发现可指出的扣分点。
证据显示：目标受众（Pydantic AI开发者）与场景（指令型技能用harness即可、需远程注册表/捆绑文件用本包）在README中明确划分并附对比链接；能力边界诚实（allowed-tools等frontmatter字段被明确声明为'不限制任何行为'）；Python 3.10–3.14矩阵、按需extras（git/s3/opensandbox/localsandbox，且localsandbox对3.10/3.11有清晰降级路径）。扣分处：技能触发依赖模型自主调用load_capability，静态证据无法证明加载选择的精确度；trigger_precision计2分。
证据显示：MIT LICENSE文件与pyproject声明一致、hatch-vcs从git tag取版本并含fallback、v1→v2迁移指南与破坏性变更清单、SECURITY.md含私有漏洞报告流程与7天响应承诺、文档strict构建纳入CI。扣分处：仓库内未见CHANGELOG文件（仅版本标签与迁移指南）；examples/FAQ内容主要在站外文档中，源文件内不可直接验证；单作者维护，长期维护责任有限。后两项及versioning_changelog计2分。
证据显示：输出可用性由端到端测试钉死（load_capability→read_skill_resource→run_skill_script全链路）；边际价值明确——README逐条列出对harness的补充（远程注册表、捆绑文件执行、${SKILL_DIR}解析、编程式技能）并诚实建议'纯指令技能直接用harness'；成本方面有长清单截断（'...and 10 more'）、无捆绑文件时不注册工具以节省上下文等设计。三 Criterion 均有具体文件证据支持，满分。
证据显示：README的行为声明（加载门控、占位符解析、目录不含SKILL.md不算技能、名称/目录必须匹配）几乎都能在测试文件中找到对应钉死测试，声称与代码可追溯。扣分处：外部文档站（安全模型、对比页）的内容不在审查范围内，跨源印证只能部分完成；CI徽章（SonarCloud）状态无法静态核实。cross_source_corroboration与fact_inference_separation计2分，claim_traceability满分。
- 默认脚本执行器在宿主机以子进程运行技能脚本；处理不可信注册表（Git/S3）技能时必须显式配置沙箱执行器，否则脚本直接在宿主执行。
- frontmatter中的 allowed-tools 等行为字段在本包中完全不起作用，不要据此假定技能被限制。
- 加载门控只阻止'未加载即读文件'，不构成对恶意技能指令本身或其脚本副作用的防御；源文件自带'不可信技能=不可信代码'警告。
- 采用前自行核对外部文档中的安全模型页面；本次静态审查未能覆盖站外内容。
- 单作者维护且无CHANGELOG文件，升级依赖版本矩阵（尤其是pydantic-ai-slim与harness联动）时留意测试下限作业的结果。
这个 Agent 能做什么，适合哪些场景？
pydantic-ai-skills 是一个 Python 包，为 Pydantic AI 实现 Agent Skills（agentskills.io 规范）支持，核心机制是渐进式披露：模型初始只看到每个技能的名称和描述，需要时才加载完整指令或读取参考文档、运行脚本。它建立在 pydantic-ai-harness 之上并委托其处理 SKILL.md 的解析、验证与指令渲染，自己补齐了 harness 刻意不做的能力：Git 和 S3 远程技能注册表（支持过滤、前缀、重命名、合并等组合操作）、捆绑文件的读取与执行（read_skill_resource 和 run_skill_script 两个工具）、沙箱执行、${SKILL_DIR} 路径解析，以及在 Python 中以装饰器或数据类定义程序化技能。每个技能都成为 Pydantic AI 的延迟加载能力（deferred capability），通过内置的 load_capability 工具按需激活。项目采用 MIT 许可证，要求 Python 3.10+，文档站含视频教程和 v1 到 v2 的迁移指南。
该包读取遵循 agentskills.io 规范的技能目录，每个目录必须包含带 YAML frontmatter（name 和 description 字段）的 SKILL.md，可选地附带参考文档、脚本和资源文件。运行时通过 SkillsCapability 将本地目录接入 Pydantic AI Agent；通过 GitSkillsRegistry 等注册表从 Git 仓库（如 anthropics/skills）或 S3 拉取技能，并可用 include/exclude 为不同 agent 分配技能子集。模型先看到技能名称与描述，再调用 Pydantic AI 的 load_capability 加载具体技能，之后可用 read_skill_resource(skill_name, resource_name) 读取捆绑文件、用 run_skill_script(skill_name, script_name, args) 执行捆绑脚本；未加载的技能默认被这两个工具拒绝。它还提供 ${SKILL_DIR} 占位符解析、自定义脚本执行器、容器或虚拟文件系统沙箱，以及用装饰器或数据类在 Python 中定义的技能，纳入同一目录管理。
- 用 Pydantic AI 构建研究助手的团队，希望按需加载不同任务的指令集（如 arXiv 检索），而不用把所有技能说明塞进系统提示词
- 技能库持续增长的团队，需要从 Git 仓库或 S3 集中分发技能，并用过滤、重命名、合并等组合操作为不同 agent 定制技能子集
- 使用 Anthropic skills 仓库等包含参考文档和可执行脚本的技能包的开发者，需要技能附带的脚本原样运行而非仅解析指令
- 安全敏感环境的工程师，希望不可信技能脚本在容器或虚拟文件系统中沙箱执行，而不是直接跑在宿主机上
- 已有纯指令型技能且只需要 SKILL.md 解析的团队，可评估是否直接用 pydantic-ai-harness 以减少依赖
- 从 v1 迁移的现有用户，需要按迁移指南处理 SkillsToolset、SkillsDirectory 等已移除的 API
这个 Agent 有哪些优点和局限？
- 渐进式披露机制让技能库可以扩展而不占用提示词空间：模型只先看到名称和描述，其余按需加载
- 在 harness 之上补齐了远程注册表（Git、S3 及组合操作）、捆绑文件读写执行、程序化技能等能力，可直接使用 Anthropic skills 仓库这类带脚本的技能包
- 对不可信脚本提供容器或虚拟文件系统沙箱执行，并提供 include/exclude 技能子集分配等安全与治理手段
- 与 Anthropic 的 Agent Skills 开放格式（agentskills.io）对齐，技能即文件夹、可移植可审计；文档完整且提供 v2 迁移指南
- v2 是破坏性更新：SkillsToolset、SkillsDirectory、reload() 和 list_skills / load_skill 工具已被移除，v1 用户需按迁移指南改造
- 强依赖 pydantic-ai-harness 和 Pydantic AI 框架，技能的解析、验证与渲染逻辑在上游，脱离该生态无法使用
- 如果技能只是纯指令，README 建议直接用 harness，因为它依赖更小、行为一致——引入本包会增加不必要的体积
- frontmatter 中如 allowed-tools 等行为字段在本运行时不生效、不会限制任何东西，从其他支持这些字段的平台迁移时可能产生安全假设落差
- 使用远程技能引入供应链风险：恶意技能可诱导 agent 调用工具或执行代码，官方文档要求审计任何未知来源的技能
如何安装或部署这个 Agent？
要求 Python 3.10+。推荐使用 uv 安装：
uv add pydantic-ai-skills也可使用 pip：
pip install pydantic-ai-skills该包依赖并委托给 pydantic-ai-harness（安装时会一并引入）。文档地址：https://dougtrajano.github.io/pydantic-ai-skills
如何使用这个 Agent？
将 SkillsCapability 指向技能目录并加入 Agent：
python
from pydantic_ai import Agent
from pydantic_ai_skills import SkillsCapabilityagent = Agent(model='gateway/openai:gpt-5.2',
instructions='You are a helpful research assistant.',
capabilities=[SkillsCapability('./skills')],
)
result = await agent.run('What are the last 3 papers on arXiv about machine learning?')
print(result.output)从远程仓库拉取技能：
python
from pydantic_ai_skills import GitSkillsRegistry, SkillsCapabilitycapability = SkillsCapability('./skills',
registries=[GitSkillsRegistry('https://github.com/anthropics/skills', path='skills')],
)
技能目录结构：my-skill/ 下放必填的 SKILL.md（YAML frontmatter 中的 name 需与目录名一致、最长 64 字符小写连字符格式，description 最长 1024 字符），可选 REFERENCE.md、scripts/ 和 resources/。模型通过 load_capability 按需加载技能，再调用 read_skill_resource 或 run_skill_script 访问文件和脚本。
这个 Agent 与同类方案有什么区别？
README 明确与 pydantic-ai-harness 对比：harness 的 Skills 能力只做本地 SKILL.md 解析并转为延迟加载能力，不枚举、读取或执行捆绑文件，也无远程源概念；本包委托 harness 并补齐远程注册表、捆绑文件执行、沙箱和程序化技能。若技能仅是指令，可直接用更轻的 harness；功能级对比见官方 comparison 文档。