# Pydantic AI Skills

> 仓库地址：https://github.com/DougTrajano/pydantic-ai-skills
> 作者/组织：DougTrajano
> 成熟度：production
> 分析日期：2026-04-15

## 一句话总结
在 Pydantic AI 框架中实现 agentskills.io 标准的 type-safe skill 加载器，通过 progressive disclosure 优化 token 消耗。

## 项目定位与架构
Pydantic AI Skills 解决的问题是：如何将 agentskills.io 开放标准优雅地集成到 Pydantic AI 的类型安全架构中。它在保持与 Anthropic 原始规范完全兼容的同时，利用 Pydantic 的 dataclass 和 type hints 提供编译时安全性。

Skill 定义支持两种方式：**filesystem-based**（目录 + Markdown 文件）和 **programmatic**（Python decorators 或 dataclasses）。加载支持多目录源和 progressive disclosure（按需加载减少 token 消耗）。

## 关键技术特性
- **Progressive Disclosure**：增量加载 skill 信息，减少不必要的 token 消耗
- **Dual Skill Definition**：filesystem-based（Markdown）+ programmatic（decorators/dataclasses）
- **Type Safety**：dataclass-based structures、type hints、automatic validation
- **Multi-source Loading**：支持从多个目录加载 skill
- **Built-in Security**：path traversal 防护 + safe script execution
- **Metadata Validation**：skill name（lowercase/digits/hyphens，max 64 chars）和 description（max 1024 chars）约束

## 设计亮点与创新
将"文件即 skill"的 agentskills.io 哲学与 Pydantic 的 type-safe 世界完美融合。programmatic skill creation 通过 decorator 模式大幅降低了 skill 开发门槛。

## 局限性与风险
- 绑定 Pydantic AI 框架，不适用于其他 Python AI 框架
- 运行时 script execution 的安全边界需严格配置

## 与生态系统的关联
是 agentskills.io 标准在 **Python 类型安全生态**中的参考实现。与 skillsdotnet（C# 实现）共同证明了标准的跨语言可移植性。