pydantic-ai-skills

A standardized, composable framework for building and managing Agent Skills within the Pydantic AI ecosystem.

Agent Skills are modular collections of instructions, scripts, tools, and resources that enable AI agents to progressively discover, load, and execute specialized capabilities for domain-specific tasks.

This package implements the Agent Skills specification for Pydantic AI using a tool-calling approach, maintaining full compatibility with the specification while adapting the loading mechanism for Pydantic AI's architecture. Agent Skills is an open format maintained by Anthropic and open to contributions from the community.

Features

• Progressive Disclosure - Load skill information only when needed, reducing token usage
• Agent Skills Spec - Fully compatible with the Agent Skills open format
• Filesystem Skills - Define skills as filesystem directories with Markdown files and scripts
• Programmatic Skills - Create skills dynamically in Python code using decorators or dataclasses
• Type-Safe - Built with Python dataclasses and type hints
• Validation - Automatic validation of skill metadata and structure
• Multiple Directories - Load skills from multiple sources
• Security - Path traversal prevention and safe script execution

Full documentation available at: https://dougtrajano.github.io/pydantic-ai-skills

Installation

pip install pydantic-ai-skills

For development:

pip install pydantic-ai-skills[test]  # Includes pytest and coverage tools

Video Tutorials

Learn how to use pydantic-ai-skills through these video tutorials:

Basic Usage

Get started with your first skill and agent:

Advanced Usage

Master advanced integration patterns:

Programmatic Skills

Create dynamic skills with Python:

Quick Start

We recommend using SkillsCapability, which is based on the Pydantic AI Capabilities API. It bundles the skills tools and instructions into a single object that can be added to agents. This provides a more streamlined and integrated way to use agent skills.

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'])],
)

Alternatively, use SkillsToolset directly when your app is built around toolsets=[...].

from pydantic_ai import Agent
from pydantic_ai_skills import SkillsToolset

# Initialize Skills Toolset with one or more skill directories
skills_toolset = SkillsToolset(directories=["./skills"])

# Create agent with skills as a toolset
agent = Agent(
    model='gateway/openai:gpt-5.2',
    instructions='You are a helpful research assistant.',
    toolsets=[skills_toolset]
)

# Use agent - skills tools are available for the agent to call
user_prompt = "What are the last 3 papers on arXiv about machine learning?"

nodes = []
async with agent.iter(user_prompt) as agent_run:
    async for node in agent_run:
        nodes.append(node)
        print(node)

Output:

UserPromptNode(user_prompt='What are the last 3 papers on arXiv about machine learning?', instructions_functions=[], system_prompts=('You are a helpful research assistant.',), system_prompt_functions=[SystemPromptRunner(function=<function add_skills_to_system_prompt at 0x110e951c0>, dynamic=False, _takes_ctx=False, _is_async=False)], system_prompt_dynamic_functions={})
ModelRequestNode(request=ModelRequest(parts=[SystemPromptPart(content='You are a helpful research assistant.', timestamp=datetime.datetime(2025, 12, 18, 23, 27, 16, 616893, tzinfo=datetime.timezone.utc)), SystemPromptPart(content="# Skills\n\nYou have access to skills that extend your capabilities. Skills are modular packages\ncontaining instructions, resources, and scripts for specialized tasks.\n\n## Available Skills\n\nThe following skills are available to you. Use them when relevant to the task:\n\n- **arxiv-search**: Search arXiv preprint repository for papers in physics, mathematics, computer science, quantitative biology, and related fields.\n- **pydanticai-docs**: Use this skill for requests related to Pydantic AI framework - building agents, tools, dependencies, structured outputs, and model integrations.\n- **web-research**: Use this skill for requests related to web research; it provides a structured approach to conducting comprehensive web research.\n## How to Use Skills\n\n**Progressive disclosure**: Load skill information only when needed.\n\n1. **When a skill is relevant to the current task**: Use `load_skill(skill_name)` to read the full instructions.\n2. **For additional documentation**: Use `read_skill_resource(skill_name, resource_name)` to read FORMS.md, REFERENCE.md, or other resources.\n3. **To execute skill scripts**: Use `run_skill_script(skill_name, script_name, args)` with appropriate command-line arguments.\n\n**Best practices**:\n- Select skills based on task relevance and descriptions listed above\n- Use progressive disclosure: load only what you need, when you need it, starting with load_skill\n- Follow the skill's documented usage patterns and examples\n", timestamp=datetime.datetime(2025, 12, 18, 23, 27, 16, 617375, tzinfo=datetime.timezone.utc)), UserPromptPart(content='What are the last 3 papers on arXiv about machine learning?', timestamp=datetime.datetime(2025, 12, 18, 23, 27, 16, 617384, tzinfo=datetime.timezone.utc))]))
CallToolsNode(model_response=ModelResponse(parts=[ToolCallPart(tool_name='load_skill', args='{"skill_name":"arxiv-search"}', tool_call_id='call_WGBvmGWJQvOliYoG5AeP6BMh')], usage=RequestUsage(input_tokens=717, output_tokens=17, details={'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}), model_name='gpt-4o-2024-08-06', timestamp=datetime.datetime(2025, 12, 18, 23, 27, 16, tzinfo=TzInfo(0)), provider_name='openai', provider_details={'finish_reason': 'tool_calls'}, provider_response_id='chatcmpl-CoHgqj5YugHHE2ZJvnQtXx3U74Uib', finish_reason='tool_call'))
ModelRequestNode(request=ModelRequest(parts=[ToolReturnPart(tool_name='load_skill', content='# Skill: arxiv-search\n**Description:** Search arXiv preprint repository for papers in physics, mathematics, computer science, quantitative biology, and related fields.\n**Path:** /Users/dougtrajano/Library/CloudStorage/OneDrive-Personal/dev/vscode/macbook/GitHub/pydantic-ai-skills/examples/skills/arxiv-search\n\n**Available Scripts:**\n- scripts/arxiv_search.py\n\n---\n\n# arXiv Search Skill\n\nThis skill provides access to arXiv, a free distribution service and open-access archive for scholarly articles in physics, mathematics, computer science, quantitative biology, quantitative finance, statistics, electrical engineering, systems science, and economics.\n\n## When to Use This Skill\n\nUse this skill when you need to:\n\n- Find preprints and recent research papers before journal publication\n- Search for papers in computational biology, bioinformatics, or systems biology\n- Access mathematical or statistical methods papers relevant to biology\n- Find machine learning papers applied to biological problems\n- Get the latest research that may not yet be in PubMed\n\n## Skill Scripts\n\n### scripts/arxiv_search.py\n\nThe `scripts/arxiv_search.py` script accepts the following arguments:\n\n- `--query` (required): Search query string (e.g., "neural networks protein structure", "single cell RNA-seq")\n- `--max-papers` (optional): Maximum number of papers to retrieve (default: 10)\n\n### Usage Pattern\n\nUse the `run_skill_script` tool to execute the `scripts/arxiv_search.py` script. For example:\n\n```python\nrun_skill_script(\n    skill_name="arxiv-search",\n    script_name="scripts/arxiv_search.py",\n    args={"query": "your search query", "max-papers": 5}\n)\n```\n\nSearch for computational biology papers (default 10 results):\n\n```python\nrun_skill_script(\n    skill_name="arxiv-search",\n    script_name="scripts/arxiv_search.py",\n    args={"query": "protein folding prediction"}\n)\n```\n\n## Output Format\n\nThe script returns formatted results with:\n\n- **Title**: Paper title\n- **Summary**: Abstract/summary text\n- **URL**: Direct link to the paper on arXiv\n\nEach paper is separated by blank lines for readability.\n\n## Features\n\n- **Relevance sorting**: Results ordered by relevance to query\n- **Fast retrieval**: Direct API access with no authentication required\n- **Simple interface**: Clean, easy-to-parse output\n- **No API key required**: Free access to arXiv database\n\n## Dependencies\n\nThis skill requires the `arxiv` Python package. If not installed, you\'ll see an error message.\n\nTo install the package:\n\n```bash\npip install arxiv\n```\n\nThe package is not included by default since it\'s skill-specific. Install it when you first use this skill.\n\n## Notes\n\n- arXiv is particularly strong for:\n  - Compu