pydantic-ai-skills
Agent Skills for Pydantic AI.
Agent Skills are modular packages of instructions, resources, and scripts that teach an agent to
handle a specialized task. On disk, a skill is just a folder: a SKILL.md file holding a name, a
description, and Markdown instructions, plus any reference documents and executable scripts the task
needs.
Your agent starts out seeing only the name and description of each skill. When a task calls for one, it loads that skill's full instructions, and reads a reference document or runs a script only if it actually needs to. This is progressive disclosure: your skill library can grow without every skill paying for space in the prompt.
📖 Full documentation — including video tutorials.
Why This and Not pydantic-ai-harness
The harness's own Skills capability is a minimal reader: it injects SKILL.md instructions but
does not enumerate, read, or execute bundled files.
pydantic-ai-skills implements the full package — bundled resources, script execution, remote
registries, programmatic skills, and reload at runtime — so skills that ship a reference document or
a script (including those in Anthropic's skills repository)
run as written. Feature-by-feature comparison:
Why pydantic-ai-skills.
Installation
uv add pydantic-ai-skills
Millennials may continue to use pip install pydantic-ai-skills. It still works, like your Spotify
playlist from 2013.
Quick Start
Point a SkillsCapability at one or more skill directories and add it to your agent:
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(directories=['./skills'])],
)
result = await agent.run('What are the last 3 papers on arXiv about machine learning?')
print(result.output)
SkillsToolset is the same thing as a toolset, for agents built around toolsets=[...]:
from pydantic_ai_skills import SkillsToolset
agent = Agent(model='gateway/openai:gpt-5.2', toolsets=[SkillsToolset(directories=['./skills'])])
Both inject the skill catalog into the agent's instructions automatically and expose four tools:
| Tool | Purpose |
|---|---|
list_skills() | List available skills (optional — the catalog is already in the prompt) |
load_skill(name) | Read a skill's full instructions |
read_skill_resource(skill_name, resource_name) | Read a bundled file such as REFERENCE.md |
run_skill_script(skill_name, script_name, args) | Run a bundled script with named arguments |
See Quick Start.
Anatomy of a Skill
my-skill/
├── SKILL.md # Required: YAML frontmatter + Markdown instructions
├── REFERENCE.md # Optional: extra docs, read on demand
├── scripts/ # Optional: executable scripts
└── resources/ # Optional: templates, data files
---
name: my-skill
description: Brief description of what this skill does and when to use it
---
# My Skill
## When to Use This Skill
Use this skill when you need to...
## Instructions
1. Step 1
2. Step 2
name (max 64 chars, lowercase letters, numbers and hyphens) and description (max 1024 chars) are
required; other frontmatter fields are yours to use. See
Creating Skills.
Beyond the Filesystem
- Programmatic skills — define skills in Python with decorators or dataclasses.
- Registries — load skills from Git repositories, S3, or custom sources, and compose them (combine, filter, prefix, rename).
- Skill selection — give each agent a subset of a shared library with
include/exclude. - Advanced features —
reload()/auto_reload,exclude_tools, deferred loading, recursive discovery.
Security
Only use skills from sources you trust. Skills give agents new capabilities through instructions and code, so a malicious skill can direct an agent to invoke tools or execute code in ways that don't match its stated purpose — with risks including data exfiltration and unauthorized system access. Audit any skill from an unknown source before use. See Security & Deployment.
Related Resources
- Agent Skills Specification
- Anthropic Agent Skills docs and best practices
- Agent Skills Cookbook
- Pydantic AI Documentation
Contributing
Contributions are welcome — see Contributing.
Acknowledgments
Thanks to Anthropic for the Agent Skills open format, the Pydantic AI team for the framework, and the community for feedback and contributions.
This project was highly inspired by pydantic-deepagents, which provided foundational ideas and patterns for agent skills and progressive disclosure in Pydantic AI.
License
MIT License — see LICENSE.