开发与工程 pydantic-ai agent-skills progressive-disclosure skill-registries sandboxed-execution python

Pydantic AI Skills

为 Pydantic AI 提供渐进式技能加载、远程注册表、资源读取与脚本执行。

源仓库: DougTrajano/pydantic-ai-skills
Star 数: ★ 380
最近更新: 7 天前
License: MIT
主语言: Python
FA 评分: 86/100 · 表现良好

30 秒速览

运行形态: 代码库 / SDK开发框架
可在哪里用: 通用 · 跨平台OpenAI API
费用: 软件免费，模型调用费用自付
上手难度: 低 · 几分钟可跑通
开始前需要: Python 3.10+Pydantic AIpydantic-ai-harnessShell / 命令行网络访问本地文件系统
典型场景: 维护大型技能库的 Pydantic AI 团队，希望代理起始时只看到技能名称和描述，在任务确实需要时才加载完整说明与参考资料。
不适合: 只需要指令型技能、不想引入额外依赖的团队，直接用 pydantic-ai-harness 更合适
使用 Pydantic AI 之外运行时的应用，需要自行编写集成
无法审计第三方技能来源、担心数据外泄或越权访问的团队
源码审查: 86/100 · 表现良好

这个 Agent 能做什么，适合哪些场景？

Pydantic AI Skills 是一个 Python 软件包，为 Pydantic AI 接入 Agent Skills 格式，并通过渐进式披露控制上下文占用。它依赖 pydantic-ai-harness 处理 SKILL.md 的解析、校验、目录和指令渲染，自身补充 Git、S3 及自定义远程注册表，以及技能筛选、前缀、重命名和合并能力。SkillsCapability 将每项技能暴露为延迟能力，模型先看到名称和描述，需要时再通过 Pydantic AI 的 load_capability 加载完整指令。加载技能后，代理可以调用 read_skill_resource 读取随包文件，或调用 run_skill_script 以具名参数执行脚本；默认情况下，这两个工具会拒绝访问尚未加载的技能。软件包还支持 Python 定义的程序化技能、${SKILL_DIR} 路径替换，以及容器或虚拟文件系统中的沙箱执行。它适合需要完整技能资源与执行链路的 Pydantic AI 项目；如果技能只有文字指令，项目文档明确建议直接使用依赖更小的 pydantic-ai-harness。

开发者把本地技能目录传给 SkillsCapability，也可以通过 GitSkillsRegistry 从 Git 仓库加载技能；文档还列出 S3 和自定义来源。pydantic-ai-harness 负责解析并校验 SKILL.md，建立技能目录并渲染指令，而该软件包把每项技能注册为 Pydantic AI 延迟能力。模型首先只接收技能的 name 和 description，确定需要后调用内置 load_capability 获取完整指令。技能被加载后，read_skill_resource(skill_name, resource_name) 可读取 references、resources 等随包文件，run_skill_script(skill_name, script_name, args) 可使用具名参数运行 scripts 中的脚本。运行时还可解析 ${SKILL_DIR}，并可通过自定义执行器、容器或虚拟文件系统隔离脚本。它不直接规定业务输出；最终输出由使用该能力的 Pydantic AI Agent、模型和所加载技能共同决定。

维护大型技能库的 Pydantic AI 团队，希望代理起始时只看到技能名称和描述，在任务确实需要时才加载完整说明与参考资料。
需要复用 Git 仓库、S3 或自定义来源中技能的开发者，希望对多个注册表执行组合、筛选、加前缀、重命名或合并。
采用 Anthropic Agent Skills 目录结构且技能包含参考文档或可执行脚本的团队，需要在 Pydantic AI 中按原结构读取和运行这些文件。
多代理应用的维护者，希望共享同一技能库，同时用 include 和 exclude 为不同代理暴露不同子集。
需要执行第三方技能脚本的部署团队，希望通过容器、虚拟文件系统或自定义执行器降低脚本直接接触宿主机的风险。

如何安装或部署这个 Agent？

需要 Python 3.10 或更高版本。使用 uv 安装：

uv add pydantic-ai-skills

也可以使用 pip：

pip install pydantic-ai-skills

软件包依赖 pydantic-ai-harness，并在代码中与 Pydantic AI 配合使用。示例模型 gateway/openai:gpt-5.2 所需的网关配置、API 凭据名称及获取方式没有在给定材料中说明；运行该示例前需要按相应 Pydantic AI 模型配置补齐这些信息。远程 Git 或 S3 注册表还需要网络访问，S3 的认证配置也未在材料中给出。

如何使用这个 Agent？

将本地技能目录作为 SkillsCapability 添加到 Pydantic AI Agent。下面是材料给出的首次调用示例；它位于支持 await 的异步上下文中：

from pydantic_ai import Agent
from pydantic_ai_skills import SkillsCapability

agent = 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)

如需从 Git 仓库引入技能，可配置 GitSkillsRegistry：

from pydantic_ai_skills import GitSkillsRegistry, SkillsCapability

capability = SkillsCapability(
    './skills',
    registries=[GitSkillsRegistry('https://github.com/anthropics/skills', path='skills')],
)

每个技能目录必须包含 SKILL.md，其 YAML 前置信息至少包含与目录名一致的 name 和 description。name 最长 64 个字符，只能使用小写字母、数字和连字符；description 最长 1024 个字符。模型加载技能后，可使用 read_skill_resource 读取随包文件，并使用 run_skill_script 执行技能脚本。默认访问边界会拒绝尚未加载的技能。

这个 Agent 有哪些优点和局限？

优点

渐进式披露让模型起初只接收技能名称和描述，完整说明、参考资料及脚本仅在需要时加载。
在 pydantic-ai-harness 基础上补充 Git、S3 和自定义远程来源，并支持筛选、前缀、重命名与合并。
提供 read_skill_resource 和 run_skill_script，覆盖仅解析 SKILL.md 无法处理的随包资源与脚本。
支持程序化 Python 技能、${SKILL_DIR} 替换以及容器、虚拟文件系统和自定义执行器。

局限

它依赖 Pydantic AI 和 pydantic-ai-harness；若项目不采用该运行时，需要自行进行集成。
技能指令和代码可能导致数据外泄或未授权系统访问，未知来源必须在使用前审计。
SKILL.md 中的 allowed-tools 等行为字段会被接受但不会产生限制效果，不能将其视为权限控制。
v2 与 v1 不兼容：SkillsToolset、SkillsDirectory、reload()、list_skills 和 load_skill 已被移除，需要迁移到 harness 与 load_capability。
如果技能只有文字指令，项目自身建议直接使用更小的 pydantic-ai-harness，因此该软件包可能增加不必要的依赖。

这个 Agent 与同类方案有什么区别？

与 pydantic-ai-harness 相比，本项目把 harness 作为依赖，并继续由它负责 SKILL.md 解析、校验、目录和指令渲染。harness 的 Skills 能力只从本地目录读取技能并将其转换为延迟能力，不枚举、读取或执行技能随包文件，也不提供远程来源。本项目增加 Git、S3 和自定义注册表、注册表组合、read_skill_resource、run_skill_script、沙箱执行、${SKILL_DIR} 替换及程序化技能。如果只需要纯文本技能说明，文档建议直接选择 harness；需要远程技能或随包资源和脚本时，本项目覆盖范围更完整。

与相关度最高的同类 agent 并排比较关键指标。

Agent	源码审查	形态 / 费用	Star	最近更新	主语言	完整支持的平台
Pydantic AI Skills 当前	86 · 表现良好	代码库 / SDK免费 + 模型费	★ 380	7 天前	Python	OpenAI API
VT Code 终端编码智能体	66 · 存在缺口	命令行工具免费 + 模型费	★ 884	今天	Rust	OpenAI API
FastAgent	46 · 缺口较多	命令行工具免费 + 模型费	★ 3.9k	1 天前	Python	Codex · OpenAI API · Claude API
AgenticX 多智能体平台	64 · 存在缺口	命令行工具免费 + 模型费	★ 593	今天	Python	Claude Code · OpenAI API · Claude API

FollowAgents 如何评估这个 Agent？

FollowAgents 源码审查 · FARS-2.1

表现良好

86/ 100 五分制 4.3 / 5

本评测基于 2026年9月7日的源码；此后该项目发布了 1 个正式版本，尚未复审。分数与结论只代表评测时的版本。最近版本 ↓

信任安全 21/29

可靠稳定 14/14

适用触发 16/18

规范维护 16/18

有效结果 13/13

证据核验 6/8

查看各维度的扣分理由

信任安全21 / 29 · 3.6/5

证据显示：技能文件工具默认拒绝未加载的技能（测试明确验证拒绝路径）、沙箱staging跳过越界符号链接并告警、避免/tmp工作目录、 SECURITY.md 明确声明'加载不可信技能等同于运行不可信代码'的信任边界。扣分处：默认脚本执行器（LocalSkillScriptExecutor）仍在宿主机上以子进程运行脚本，沙箱为可选extra而非默认；没有面向最终用户的人工确认机制，只有加载门控；注册表同步的回滚/恢复路径无证据。最低权限与外部效应因宿主机默认执行仅得2分；用户确认仅1分；回滚1分。

可靠稳定14 / 14 · 5.0/5

证据显示：测试覆盖构造期校验错误（harness的ValueError原样透出）、include/exclude拼写错误报错并列出可用技能、缺失optional extra时ImportError指名extra名称、沙箱复用/重建/生命周期的边界情况均有钉死测试。依赖下限（pyyaml 6.0.1、pytest-asyncio 0.23.5等）在CI的test-lowest-versions作业中实测验证。一致性、依赖可用性与错误信息质量均有充分证据支持满分；未发现可指出的扣分点。

适用触发16 / 18 · 4.4/5

证据显示：目标受众（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分。

规范维护16 / 18 · 4.4/5

证据显示：MIT LICENSE文件与pyproject声明一致、hatch-vcs从git tag取版本并含fallback、v1→v2迁移指南与破坏性变更清单、SECURITY.md含私有漏洞报告流程与7天响应承诺、文档strict构建纳入CI。扣分处：仓库内未见CHANGELOG文件（仅版本标签与迁移指南）；examples/FAQ内容主要在站外文档中，源文件内不可直接验证；单作者维护，长期维护责任有限。后两项及versioning_changelog计2分。

有效结果13 / 13 · 5.0/5

证据显示：输出可用性由端到端测试钉死（load_capability→read_skill_resource→run_skill_script全链路）；边际价值明确——README逐条列出对harness的补充（远程注册表、捆绑文件执行、${SKILL_DIR}解析、编程式技能）并诚实建议'纯指令技能直接用harness'；成本方面有长清单截断（'...and 10 more'）、无捆绑文件时不注册工具以节省上下文等设计。三 Criterion 均有具体文件证据支持，满分。

证据核验6 / 8 · 3.8/5

证据显示：README的行为声明（加载门控、占位符解析、目录不含SKILL.md不算技能、名称/目录必须匹配）几乎都能在测试文件中找到对应钉死测试，声称与代码可追溯。扣分处：外部文档站（安全模型、对比页）的内容不在审查范围内，跨源印证只能部分完成；CI徽章（SonarCloud）状态无法静态核实。cross_source_corroboration与fact_inference_separation计2分，claim_traceability满分。

风险与缓解建议

默认脚本执行器在宿主机以子进程运行技能脚本；处理不可信注册表（Git/S3）技能时必须显式配置沙箱执行器，否则脚本直接在宿主执行。
frontmatter中的 allowed-tools 等行为字段在本包中完全不起作用，不要据此假定技能被限制。
加载门控只阻止'未加载即读文件'，不构成对恶意技能指令本身或其脚本副作用的防御；源文件自带'不可信技能=不可信代码'警告。
采用前自行核对外部文档中的安全模型页面；本次静态审查未能覆盖站外内容。
单作者维护且无CHANGELOG文件，升级依赖版本矩阵（尤其是pydantic-ai-slim与harness联动）时留意测试下限作业的结果。

证据充分度：低评估于 2026年9月7日审查版本 c2e576176677 评估后仓库已有新提交，评分可能未覆盖最新改动

评估证据 README.md LICENSE SECURITY.md pyproject.toml workflows/ci.yml workflows/gh-pages.yml tests/__init__.py tests/test_capability.py tests/test_executors.py

查看完整评分方法 →

常见问题

可以直接使用现有 Agent Skills 目录吗？

可以。技能是包含必需 SKILL.md 以及可选参考文档、scripts 和 resources 的目录。name 必须与目录名一致，并符合长度和字符限制。

执行第三方技能脚本安全吗？

不能默认认为安全。文档警告恶意技能可能诱导代理调用工具、泄露数据或进行未授权访问；应先审计未知来源，并考虑容器、虚拟文件系统或自定义沙箱执行器。

它会强制执行 SKILL.md 中的 allowed-tools 吗？

不会。除 name 和 description 外的前置信息可以被接受，但属于非生效字段；allowed-tools 不会在这里限制工具权限。

升级自 v1 是否需要修改代码？

需要。v2 是一次不兼容升级，移除了 SkillsToolset、SkillsDirectory、reload()、list_skills 和 load_skill，改用 pydantic-ai-harness 以及 Pydantic AI 的 load_capability。

必须使用 OpenAI 模型吗？

该软件包以 Pydantic AI 能力的形式集成，材料中的可运行示例使用 gateway/openai:gpt-5.2，但没有声明技能系统只能使用 OpenAI。其他模型的具体配置和兼容性未在给定材料中说明。

Pydantic AI Skills

30 秒速览

这个 Agent 能做什么，适合哪些场景？

如何安装或部署这个 Agent？

如何使用这个 Agent？

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

FollowAgents 如何评估这个 Agent？

最近版本

常见问题

对比同类 Agent

开源编程 Agent 横向对比

相关 Agents

VT Code 终端编码智能体

FastAgent

AgenticX 多智能体平台

Marvin – Python AI 开发框架