Quick Start

Quick Start

This guide walks you through creating and using agents with skills support, from basic to advanced usage.

Video Tutorials

For a visual walkthrough of the basics, check out the video tutorials:

Basic Usage

Learn how to create your first skill and initialize an agent with the SkillsToolset:

Advanced Usage

Explore advanced patterns and skill integration techniques:

Programmatic Skills

Create skills dynamically using Python decorators:

Basic Usage

View the complete example: basic_usage.py

1. Create Your First Skill

Create ./skills/pydanticai-docs/SKILL.md:

---
name: pydanticai-docs
description: Quick reference for Pydantic AI framework
---

# Pydantic AI Docs

Quick reference for building agents with Pydantic AI.

## Instructions

For detailed information, fetch the full docs at:
https://ai.pydantic.dev/llms-full.txt

## Quick Examples

**Basic Agent:**

```python
from pydantic_ai import Agent

agent = Agent('openai:gpt-5.2')
result = agent.run_sync('Your question')
```

With Tools:

@agent.tool
async def my_tool(ctx: RunContext[str]) -> str:
    return ctx.deps

2. Create an Agent with Skills

Create agent.py:

import asyncio
from pydantic_ai import Agent, RunContext
from pydantic_ai_skills import SkillsToolset

async def main():
    # Initialize skills
    skills_toolset = SkillsToolset(directories=["./skills"])

    # Create agent
    agent = Agent(
        model='openai:gpt-5.2',
        instructions="You are a helpful assistant.",
        toolsets=[skills_toolset]
    )

    # Add skills instructions to agent
    @agent.instructions
    async def add_skills(ctx: RunContext) -> str | None:
        """Add skills instructions to the agent's context."""
        return await skills_toolset.get_instructions(ctx)

    # Run the agent
    result = await agent.run("How do I create a Pydantic AI agent with tools?")
    print(result.output)

if __name__ == "__main__":
    asyncio.run(main())

3. Set Your API Key

export OPENAI_API_KEY="your-api-key-here"

4. Run the Agent

python agent.py

The agent will use the pydanticai-docs skill to answer your question!

How It Works

When you initialize the skills toolset:

1. Discovery: Scans ./skills/ for skill directories with SKILL.md files
2. Registration: Registers four tools (list_skills, load_skill, read_skill_resource, run_skill_script)
3. Instructions: Skills overview is added to the agent via @agent.instructions
4. Execution: Agent discovers, loads, and uses skills as needed

Add a Script-Based Skill

Create a skill that executes Python scripts:

./skills/
└── calculator/
    ├── SKILL.md
    └── scripts/
        └── calculate.py

SKILL.md:

---
name: calculator
description: Perform calculations using Python
---

# Calculator Skill

Use the `calculate` script to perform mathematical operations.

## Usage

```python
run_skill_script(
    skill_name="calculator",
    script_name="calculate",
    args=["2 + 2"]
)
```

scripts/calculate.py:

import sys

if len(sys.argv) < 2:
    print("Usage: calculate.py <expression>")
    sys.exit(1)

expression = sys.argv[1]
try:
    result = eval(expression)
    print(f"Result: {result}")
except Exception as e:
    print(f"Error: {e}")

Advanced Examples

Programmatic Skills

Create skills directly in Python code for dynamic capabilities:

from pydantic_ai import Agent, RunContext
from pydantic_ai.toolsets.skills import Skill, SkillsToolset

# Create a programmatic skill
my_skill = Skill(
    name='data-processor',
    description='Process and analyze data',
    content='Use this skill for data analysis tasks.'
)

# Add dynamic resources and scripts
@my_skill.resource
def get_schema() -> str:
    """Get current data schema."""
    return "Available fields: id, name, value, timestamp"

@my_skill.script
async def process_data(ctx: RunContext[MyDeps], query: str) -> str:
    """Process data based on query."""
    results = await ctx.deps.process(query)
    return f"Processed {len(results)} records"

# Use with toolset
skills_toolset = SkillsToolset(skills=[my_skill])

Learn more in the Programmatic Skills guide.

Multiple Skill Directories

Load skills from multiple locations:

from pydantic_ai_skills import SkillsToolset

skills_toolset = SkillsToolset(
    directories=[
        "./skills/research",    # Domain-specific skills
        "./skills/data",        # Data processing skills
        "./shared-skills",      # Shared across projects
    ],
    validate=True,
    script_timeout=60
)

print(f"Loaded {len(skills_toolset.skills)} skills")
for name, skill in skills_toolset.skills.items():
    print(f"- {name}: {skill.metadata.description}")

Research Assistant

An agent specialized for searching academic papers:

import asyncio
from pydantic_ai import Agent
from pydantic_ai_skills import SkillsToolset

async def main():
    skills_toolset = SkillsToolset(directories=["./examples/skills"])

    agent = Agent(
        model='openai:gpt-5.2',
        instructions="You are a research assistant specializing in academic papers.",
        toolsets=[skills_toolset]
    )

    @agent.instructions
    async def add_skills(ctx: RunContext) -> str | None:
        """Add skills instructions to the agent's context."""
        return await skills_toolset.get_instructions(ctx)

    result = await agent.run(
        "Find the 5 most recent papers on transformer architectures"
    )
    print(result.output)

if __name__ == "__main__":
    asyncio.run(main())

Dynamic Skill Refresh

Reload skills after filesystem changes:

import asyncio
from pydantic_ai import Agent
from pydantic_ai_skills import SkillsToolset

async def main():
    toolset = SkillsToolset(directories=["./skills"])
    agent = Agent(
        model='openai:gpt-5.2',
        instructions="You are a helpful assistant.",
        toolsets=[toolset]
    )

    @agent.instructions
    async def add_skills(ctx: RunContext) -> str | None:
        """Add skills instructions to the agent's context."""
        return await toolset.get_instructions(ctx)

    # Use agent
    result = await agent.run("What skills are available?")
    print(result.output)

    # ... User adds new skill to ./skills/ ...

    # To pick up new skills, recreate the toolset and agent
    toolset = SkillsToolset(directories=["./skills"])
    agent = Agent(
        model='openai:gpt-5.2',
        instructions="You are a helpful assistant.",
        toolsets=[toolset]
    )

    @agent.instructions
    async def add_skills_again(ctx: RunContext) -> str | None:
        """Add skills instructions to the agent's context."""
        return await toolset.get_instructions(ctx)

    print(f"\nReloaded. Now have {len(toolset.skills)} skills")

    result = await agent.run("What skills are available now?")
    print(result.output)

if __name__ == "__main__":
    asyncio.run(main())

Note: To pick up new skills after modifying the filesystem, you'll need to recreate the SkillsToolset instance or restart your application.

Programmatic Skill Access

Access skills directly without an agent:

from pydantic_ai_skills import SkillsToolset

toolset = SkillsToolset(directories=["./skills"])

# Get a specific skill
skill = toolset.get_skill("arxiv-search")

print(f"Skill: {skill.name}")
print(f"Description: {skill.metadata.description}")
print(f"Content: {len(skill.content)} characters")

# List scripts
if skill.scripts:
    print("\nScripts:")
    for script in skill.scripts:
        print(f"  - {script.name} ({script.path})")

# List resources
if skill.resources:
    print("\nResources:")
    for resource in skill.resources:
        print(f"  - {resource.name}")

Custom Discovery

Use the discovery function directly:

from pydantic_ai_skills import discover_skills

# Discover skills without creating a toolset
skills = discover_skills(
    directories=["./skills", "./more-skills"],
    validate=True
)

# Filter by category
research_skills = [
    s for s in skills
    if s.metadata.extra.get("category") == "research"
]

print(f"Found {len(research_skills)} research skills")

Example Skills

The repository includes several example skills in examples/skills/:

ArXiv Search

• Type: Script-based skill
• Features: Search academic papers using Python script
• Location: examples/skills/arxiv-search/

Web Research

• Type: Instruction-only skill
• Features: Structured research methodology
• Location: examples/skills/web-research/

Pydantic AI Docs

• Type: Documentation reference skill
• Features: Quick access to Pydantic AI documentation
• Location: examples/skills/pydanticai-docs/

Next Steps

• Core Concepts - Understand the architecture
• Creating Skills - Build your own skills
• API Reference - Detailed API documentation