tools-only 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:
- Discovery: Scans
./skills/for skill directories withSKILL.mdfiles - Registration: Registers four tools (
list_skills,load_skill,read_skill_resource,run_skill_script) - Instructions: Skills overview is added to the agent via
@agent.instructions - 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
SkillsToolsetinstance 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