Author(s): douglas trajano
Originally published on Towards AI.
Give your AI agents superpowers – without distorting their context window.
The agentic AI landscape is rapidly evolving. We moved from simple chatbots to autonomous systems that plan, reason, and execute multi-step workflows. But as agents become more capable, a familiar engineering problem emerges: How do you add new capabilities without turning your system prompt into an unmanageable monolith?
That’s the problem pedantic-ai-skills Solves. It is a standardized, composable framework for building and managing agent skills within the Pydentic AI ecosystem. Inspired by Anthropic’s Agent Skills open standard – released in December 2025 as a vendor-neutral specification for portable AI capabilities – this library brings the same progressive disclosure pattern to any pedantic AI agent.
Problem: context window bloat
If you’ve created production agents, you know the pain. You start with a clean system prompt, then add instructions to search the web, then database queries, then report generation, then… suddenly your agent is consuming thousands of tokens before the user even reads the message.
Each new ability means more instructions filled into the prompt. Agents get confused. The cost of the token is skyrocketing. Maintenance becomes a nightmare.
pedantic-ai-skills Takes a different approach: progressive disclosure. Skills are discovered and loaded on demand, taking into account your agent’s context. The agent loads full instructions for a skill only when it actually needs it.
how it works
The library implements a tool-based approach that provides agents structured access to skills using 4 tools:
list_skills()Find all available skills (name + description).load_skill(name)Load complete instructions for a specific skill.read_skill_resource(skill_name, resource_name)Access additional documents, templates or data files.run_skill_script(skill_name, script_name, args)Execute a Python script defined within a skill.
This progressive approach means that an agent with 50 skills does not need to preload all 50 sets of instructions. It looks at the menu, chooses what it needs, and only goes deeper when necessary.
launch
You can install it instantly using the command given below.
pip install pydantic-ai-skills
your first skill
Every file-based skill is just a directory SKILL.md file. Frontmatter contains metadata, and the Markdown body contains instructions for the agent.(1)
create a file on ./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-4o')
result = agent.run_sync('Your question')
### Wiring Skills to an AgentNow create your agent with the `SkillsToolset`:
```python
import asyncio
from pydantic_ai import Agent, RunContext
from pydantic_ai_skills import SkillsToolset
async def main():
# Initialize skills from a directory
skills_toolset = SkillsToolset(directories=("./skills"))
# Create agent with skills as a toolset
agent = Agent(
model='openai:gpt-4o',
instructions='You are a helpful assistant.',
toolsets=(skills_toolset)
)
# Inject skill descriptions into the agent's instructions
@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 will discover and use skills automatically
result = await agent.run(
"How do I create a Pydantic AI agent with tools?"
)
print(result.output)
if __name__ == "__main__":
asyncio.run(main())
That’s it. The agent now automatically detects pydanticai-docs The skill loads it when relevant, and uses its instructions to answer questions about pedantic AI.
Script-Based Skills: Going Beyond Instructions
Skills are not limited to curriculum instructions. You can bundle executable Python scripts that agents can run on demand. Here is the calculator skill with a script:
./skills/
└── calculator/
├── SKILL.md
└── scripts/
└── calculate.py
skills.md:
---
name: calculator
description: Perform calculations using Python
---
# Calculator SkillUse the `calculate` script to perform mathematical operations.
script/calculation.py:
"""Evaluate a Python expression and return the result as JSON."""import argparse
import json
import sys
parser = argparse.ArgumentParser()
parser.add_argument('--expression', required=True, help='Python expression to evaluate')
args = parser.parse_args()
try:
result = eval(args.expression)
print(json.dumps({'result': result}))
except Exception as e:
print(f'Error: {e}', file=sys.stderr)
sys.exit(1)
When an agent encounters a math problem, he or she can call run_skill_script(skill_name="calculator", script_name="calculate", args={"expression": "2**10"}) get more {"result": 1024} Back.
Programmatic Skills: Dynamic Abilities in Code
File-based skills are great for static, shareable capabilities. But sometimes you need skills that are generated at runtime, depend on live configuration, or require dependency injection. it is right here programmatic skills Come in.
from pydantic_ai import Agent, RunContext
from pydantic_ai_skills import Skill, SkillsToolset, SkillResource# Create a skill object directly in Python
my_skill = Skill(
name='data-processor',
description='Process and analyze data',
content='Use this skill for data analysis tasks.',
resources=(
SkillResource(
name='reference',
content='## ReferencennStatic reference documentation here...'
)
)
)
# Add a dynamic resource via decorator
@my_skill.resource
def get_schema() -> str:
"""Get current data schema."""
return "Available fields: id, name, value, timestamp"
# Add an executable script via decorator
@my_skill.script
async def process_data(ctx: RunContext, query: str) -> str:
"""Process data based on query."""
results = await ctx.deps.process(query)
return f"Processed {len(results)} records"
# Wire it up
skills_toolset = SkillsToolset(skills=(my_skill))
Programmatic skills support full RunContext Dependency injection allows your scripts and resources to access databases, APIs, and any other runtime dependencies that your agent requires.
Decorator Pattern: Inline Skill Definitions
For skills strongly associated with agent initialization @toolset.skill() The decorator provides the most concise syntax:
from pydantic_ai import Agent, RunContext
from pydantic_ai_skills import SkillsToolsetskills_toolset = SkillsToolset()
@skills_toolset.skill()
def data_analyzer() -> str:
"""Analyze data from various sources."""
return """
# Data Analysis SkillUse this skill to analyze datasets and generate insights.
"""@data_analyzer.resource
async def get_schema(ctx: RunContext) -> str:
"""Get database schema from live connection."""
schema = await ctx.deps.database.get_schema()
return f"## Current Scheman{schema}"agent = Agent(
model='openai:gpt-4o',
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)
Blend of file-based and programmatic skills
One of the most powerful patterns is a combination of both approaches – static, reusable skills from files with dynamic, runtime-specific skills defined in code:
from pydantic_ai_skills import SkillsToolset# Load file-based skills AND add programmatic ones
skills_toolset = SkillsToolset(
directories=(
"./skills/research", # Shared research skills
"./skills/data", # Data processing skills
),
validate=True,
)
# Add a runtime-specific skill inline
@skills_toolset.skill(name='runtime-monitor', metadata={'version': '1.0.0'})
def monitoring() -> str:
return "Monitor application runtime metrics"
Agentskills.io Compatibility
The library implements this Agentskills.io The specification, which was released by Anthropic as an open standard in December 2025 and has been adopted by Microsoft, OpenAI, Atlassian, Figma, Cursor, and GitHub. made with skill pydantic-ai-skills Are structurally compatible with Anthropic’s skills format – including SKILL.md File structure, naming conventions (lowercase, hyphen, ≤64 characters), and progressive disclosure loading patterns.
This means that skills created for this library can potentially be reused across different platforms that support the Agent Skills standard.
security considerations
As skills provide agents with new capabilities through instructions and executable code, security is critical. The library implements several security measures:
- prevention of diversion – Scripts and resources should be under the skills directory
- script timeout – Scripts expire after a configurable timeout
- safe subprocess execution — Scripts run in subprocesses with limited privileges
- Validation – Automatic validation of skill metadata and structure
The document strongly recommends only using skills obtained from trusted sources – those built in-house or obtained from verified providers.(1)
Why pedantic-AI-skills?
was inspired by the library pydantic-deepagents project, which led to several skill patterns in the Pydantic AI ecosystem. what’s set here pydantic-ai-skills apart:
- concentric circle — It does one thing well: skill management. No planning loops, no file system toolsets, no subagent delegation. Just clean, creative skills.
- drop-in integration – Works as a standard pedantic AI
ToolsetTherefore it plugs into any existing agent without architectural changes. - Type- Secure – Built on the Python dataclass and type hints with full type annotation support.
- Agentskills.io Specification – Agent skills structurally aligned with open standards.
- lightweight – Minimal dependencies; Install and use in minutes.
Real World Example: Research Assistant
Here is a full example of a research assistant using the ArXiv search skill:
import asyncio
from pydantic_ai import Agent, RunContext
from pydantic_ai_skills import SkillsToolsetasync def main():
skills_toolset = SkillsToolset(directories=("./examples/skills"))
agent = Agent(
model='openai:gpt-4o',
instructions=(
"You are a research assistant specializing in "
"academic papers."
),
toolsets=(skills_toolset)
)
@agent.instructions
async def add_skills(ctx: RunContext) -> str | None:
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())
the agent finds out arxiv-search skill, loads its instructions, and uses run_skill_script To execute the search – without any ArXiv-specific code in the agent.
what will happen next
The library is at version 0.4.1 and actively maintained. Documentation includes guides on building skills, programmatic skills, advanced features such as custom script executors and dependency injection, implementation patterns, and security best practices.
See more on:
If you’re building pedantic AI agents and want to keep them modular, maintainable, and efficient, let pydantic-ai-skills One try. Skills are the building blocks of competent agents, and progressive disclosure is how you move forward without drowning in context.
Published via Towards AI
