Introducing pydantic-ai-skills: Composable Agent Skills for the Pydantic AI Ecosystem

Author(s): Douglas Trajano Originally published on Towards AI. Give your AI agents superpowers — without bloating their context window. The Agentic AI landscape is evolving fast. We went from simple chatbots to autonomous systems that plan, reason, and execute multi-step workflows. But as agents grow 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 pydantic-ai-skills solves. It’s a standardized, composable framework for building and managing Agent Skills within the Pydantic 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 Pydantic AI agent. The Problem: Context Window Bloat If you’ve built production agents, you know the pain. You start with a clean system prompt, then add instructions for searching the web, then database queries, then report generation, then… suddenly your agent is consuming thousands of tokens before it even reads the user’s message. Every new capability means more instructions stuffed into the prompt. Agents get confused. Token costs skyrocket. Maintenance becomes a nightmare. pydantic-ai-skills takes a different approach: progressive disclosure. Skills are discovered and loaded on demand, keeping your agent’s context lean and focused. The agent only loads the full instructions for a skill when it actually needs it. How It Works The library implements a tool-based approach that gives agents structured access to skills using 4 tools: list_skills()Discover all available skills (names + descriptions). load_skill(name)Load complete instructions for a specific skill. read_skill_resource(skill_name, resource_name)Access additional documentation, templates, or data files. run_skill_script(skill_name, script_name, args)Execute Python scripts defined within a skill. This progressive approach means an agent with 50 skills doesn’t need to load all 50 sets of instructions upfront. It sees the menu, picks what it needs, and dives deeper only when required. Getting Started You can quickly install it using the command below. pip install pydantic-ai-skills Your First Skill Every file-based skill is just a directory with a SKILL.md file. The frontmatter contains metadata, and the markdown body contains instructions for the agent.[1] Create a file at ./skills/pydanticai-docs/SKILL.md: —name: pydanticai-docsdescription: Quick reference for Pydantic AI framework—# Pydantic AI DocsQuick reference for building agents with Pydantic AI.## InstructionsFor detailed information, fetch the full docs at:https://ai.pydantic.dev/llms-full.txt## Quick Examples**Basic Agent:**“`pythonfrom pydantic_ai import Agentagent = Agent(‘openai:gpt-4o’)result = agent.run_sync(‘Your question’) ### Wiring Skills to an AgentNow create your agent with the `SkillsToolset`:“`pythonimport asynciofrom pydantic_ai import Agent, RunContextfrom pydantic_ai_skills import SkillsToolsetasync 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 discovers the pydanticai-docs skill, loads it when relevant, and uses its instructions to answer questions about Pydantic AI. Script-Based Skills: Going Beyond Instructions Skills aren’t limited to text instructions. You can bundle executable Python scripts that agents can run on demand. Here’s a calculator skill with a script: ./skills/└── calculator/ ├── SKILL.md └── scripts/ └── calculate.py SKILL.md: —name: calculatordescription: Perform calculations using Python—# Calculator SkillUse the `calculate` script to perform mathematical operations. scripts/calculate.py: “””Evaluate a Python expression and return the result as JSON.”””import argparseimport jsonimport sysparser = 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 the agent encounters a math problem, it can call run_skill_script(skill_name=”calculator”, script_name=”calculate”, args={“expression”: “2**10”}) and get {“result”: 1024} back. Programmatic Skills: Dynamic Capabilities in Code File-based skills are great for stable, shareable capabilities. But sometimes you need skills that are generated at runtime, depend on live configuration, or require dependency injection. That’s where programmatic skills come in. from pydantic_ai import Agent, RunContextfrom pydantic_ai_skills import Skill, SkillsToolset, SkillResource# Create a skill object directly in Pythonmy_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.resourcedef get_schema() -> str: “””Get current data schema.””” return “Available fields: id, name, value, timestamp”# Add an executable script via decorator@my_skill.scriptasync 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 upskills_toolset = SkillsToolset(skills=[my_skill]) Programmatic skills support full RunContext dependency injection, allowing your scripts and resources to access databases, APIs, and any other runtime dependencies your agent needs. The Decorator Pattern: Inline Skill Definitions For skills tightly coupled with agent initialization, the @toolset.skill() decorator offers the most concise syntax: from pydantic_ai import Agent, RunContextfrom pydantic_ai_skills import SkillsToolsetskills_toolset = SkillsToolset()@skills_toolset.skill()def data_analyzer() -> str: “””Analyze data from various sources.””” return “”” # Data Analysis Skill Use this skill to analyze datasets and generate insights. “””@data_analyzer.resourceasync 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.instructionsasync def add_skills(ctx: RunContext) -> str | None: “””Add skills instructions to the agent’s context.””” return await skills_toolset.get_instructions(ctx) Mixing File-Based and Programmatic Skills One of the most powerful patterns is combining both approaches — stable, reusable skills from files alongside dynamic, runtime-specific skills defined in code: from pydantic_ai_skills import SkillsToolset# Load file-based skills AND add programmatic onesskills_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 the agentskills.io specification, which was released by Anthropic as an open standard in December 2025 and adopted by Microsoft, OpenAI, Atlassian, Figma, Cursor, and GitHub. Skills created with pydantic-ai-skills are structurally compatible with Anthropic’s skill format — including the SKILL.md file structure, […]