pydantic-ai-skills

Remote skill registries and bundled-file execution for Agent Skills in 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.

How This Relates to pydantic-ai-harness

pydantic-ai-harness ships a Skills capability that reads SKILL.md packages from local directories and turns each into a deferred Pydantic AI capability. It stops there by design — it does not enumerate, read, or execute bundled files, and it has no notion of a remote source.

pydantic-ai-skills is the companion that fills those gaps. It requires harness and delegates to it, so SKILL.md parsing, validation, the catalog and instruction rendering are all upstream's, and adds:

• Remote registries — Git and S3 sources, with composition (filter, prefix, rename, merge).
• Bundled files — read_skill_resource and run_skill_script, so a skill that ships a reference document or a script (including those in Anthropic's skills repository) runs as written.
• Sandboxed execution — keep untrusted scripts off the host.
• ${SKILL_DIR} resolution — harness leaves the placeholder in place; this substitutes the path.
• Programmatic skills — skills defined in Python, in the same catalog.

If your skills are instructions and nothing else, use harness directly — it is a smaller dependency and identical behaviour. Feature-by-feature: comparison.

Upgrading from v1? v2 is a clean break: SkillsToolset, SkillsDirectory, reload() and the list_skills / load_skill tools are gone, replaced by harness and Pydantic AI's own load_capability. See the migration guide.

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 libraries 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('./skills')],
)

result = await agent.run('What are the last 3 papers on arXiv about machine learning?')
print(result.output)

Or pull them from a repository: