pydantic-ai-skills Skill 技能

技能简介

pydantic-ai-skills 是 Pydantic AI Agent Skills 的远程 Skill 注册与文件执行扩展库。它基于 Pydantic AI 内置的 pydantic-ai-harness 库构建，为 Agent 提供远程 Skill 注册（Git 仓库、S3）和脚本执行能力，使 Skill 库可以真正在生产环境中实现分布式管理和渐进式加载。

Agent Skills 是一种模块化的 AI Agent 技能包格式：在磁盘上只是一个文件夹，包含一个 SKILL.md 文件（存放名称、描述和 Markdown 指令）和任意参考文档、脚本文件。Agent 启动时只看到 Skill 名称和描述，只有在任务真正需要时才会加载完整指令并执行脚本——这称为"渐进式披露"（Progressive Disclosure），可以让 Skill 库不断增长而不会让 Agent 的提示词膨胀。

pydantic-ai-skills 在 harness 的基础上增加了远程注册源（Git/S3）、捆绑文件读取与脚本运行、沙盒执行环境，以及 ${SKILL_DIR} 路径解析等关键功能。

核心能力

1. 远程 Skill 注册：从 Git 仓库或 S3 动态加载 Skill 包，支持组合（过滤、前缀、重命名、合并）
2. 捆绑文件执行：通过 read_skill_resource 读取参考文档，通过 run_skill_script 执行脚本，均在沙盒隔离环境中运行
3. 渐进式披露：Agent 仅在需要时加载完整 Skill 指令，不占用启动上下文空间
4. Programmatic Skills：用 Python 代码（装饰器或数据类）定义 Skill，无需磁盘文件
5. 沙盒执行：可选将脚本运行在容器或虚拟文件系统而非主机，保护宿主安全
6. 兼容 Anthropic Skills：直接使用 Anthropic 官方 Skills 仓库（github.com/anthropics/skills）中的 Skill 包
7. Skill 选择性暴露：通过 include / exclude 为不同 Agent 分配同一个共享 Skill 库的不同子集

安装配置

前置条件：Python 3.10+

方式一：uv 安装（推荐）

uv add pydantic-ai-skills

方式二：pip 安装

pip install pydantic-ai-skills

方式三：从源码安装（开发模式）

git clone https://github.com/DougTrajano/pydantic-ai-skills.git
cd pydantic-ai-skills
pip install -e '.[dev]'

使用步骤

第一步：初始化 SkillsCapability

在 Python 代码中创建 Agent 时，配置 SkillsCapability 指向本地 Skill 目录：

from pydantic_ai import Agent
from pydantic_ai_skills import SkillsCapability

agent = Agent(
    model='gateway/openai:gpt-5.2',
    instructions='你是一个研究助手。',
    capabilities=[SkillsCapability('./skills')],
)

第二步：从远程仓库加载 Skill

使用 GitSkillsRegistry 从远程 Git 仓库加载 Anthropic 官方 Skill 包：

from pydantic_ai_skills import GitSkillsRegistry, SkillsCapability

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

第三步：让 Agent 调用 Skill

Agent 根据任务需要，通过 Pydantic AI 内置的 load_capability 加载对应 Skill，然后使用两个扩展工具：

第四步：运行并获取结果

result = await agent.run('请总结机器学习领域最近 3 篇最热门的 arXiv 论文。')
print(result.output)

Skill 包结构

一个标准 Skill 目录结构如下：

my-skill/
├── SKILL.md      # 必需：YAML frontmatter（name + description）+ Markdown 指令
├── REFERENCE.md  # 可选：额外文档，按需读取
├── scripts/      # 可选：可执行脚本
└── resources/    # 可选：模板、数据文件等资源

SKILL.md 示例：

---
name: my-skill
description: 关于这个 Skill 用途的简要描述（最多 1024 字符）
---

# 我的 Skill

## 何时使用此 Skill

当需要……时请使用此 Skill。

## 指令

1. 第一步
2. 第二步

适用场景

1. 多 Agent 分工协作：不同 Agent 从同一个远程 Skill 仓库按需加载不同子集，实现技能共享与权限隔离
2. 企业级 Skill 管理：将 Skill 包托管在私有 Git 仓库或 S3，通过版本控制管理 Skill 发布
3. 渐进式上下文优化：大型 Skill 库（如 Anthropic 官方 Skills 仓库）以渐进式方式加载，避免上下文溢出
4. 安全脚本执行：在沙盒容器中运行 Skill 附带的脚本，防止恶意代码访问宿主系统

适用人群

• Pydantic AI 开发者：使用 Pydantic AI 构建生产级 AI Agent 的工程师
• AI 平台架构师：需要构建多租户 Skill 市场或企业 AI 能力中台
• Agent 系统研究者：关注 Skill 格式标准（Agent Skills 规范）和渐进式加载机制

工作原理

pydantic-ai-skills 的核心是 SkillsCapability 和注册表系统。SkillsCapability 初始化时扫描注册表（本地目录、Git 仓库或 S3），将所有 Skill 的 name/description 注册到 Agent 的能力列表中。Agent 在对话过程中根据用户请求决定调用哪个 Skill，通过 load_capability 加载完整指令。当 Skill 需要访问资源文件或执行脚本时，read_skill_resource 和 run_skill_script 工具负责读取捆绑文件或在沙盒中执行脚本，并将结果返回给 Agent。

官方链接

• GitHub 仓库：https://github.com/DougTrajano/pydantic-ai-skills
• PyPI 安装包：https://pypi.org/project/pydantic-ai-skills/
• 完整文档：https://dougtrajano.github.io/pydantic-ai-skills/
• 快速入门视频：https://dougtrajano.github.io/pydantic-ai-skills/quick-start/#video-tutorials
• Agent Skills 规范：https://agentskills.io/specification
• Anthropic Agent Skills：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
• Pydantic AI 文档：https://ai.pydantic.dev/