Skills: Progressive Disclosure for Agent Capabilities #3838
Description
Description
Summary
Introduce a Skill abstraction that enables on-demand loading of agent capabilities, reducing token usage and improving maintainability for complex agents.
Inspired by [Anthropic's Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) and LangChain's Deep Agents.
Problem
Currently, tools and system_prompts are statically loaded at agent initialization. For agents with many capabilities, this causes:
- Token waste: All tool descriptions are included in every request, even when not needed
- Bloated prompts: System prompts become long and unfocused
- Scalability issues: Adding more tools degrades performance
Example: User asks "What's the weather?" → All 50+ tool descriptions sent to model, wasting tokens and potentially confusing the model.
Proposed Solution: Skills
A Skill is a group of related capabilities that can be loaded on-demand:
from pydantic_ai import Agent, Skill
excel_skill = Skill(
name='excel',
description='Excel file manipulation and analysis',
instructions_file='./skills/excel/SKILL.md',
trigger_keywords=['excel', 'spreadsheet', 'xlsx', 'csv'],
tools=[read_excel, write_excel, format_cells],
)
agent = Agent(
model='openai:gpt-4',
skills=[excel_skill, pdf_skill],
)
# Skills activate automatically based on user input
result = await agent.run("Analyze this Excel file")
# → Only Excel instructions and tools sent to modelProgressive Disclosure
Level 1: Metadata (always loaded)
├── name, description, trigger_keywords
Level 2: Instructions (loaded on activation)
└── SKILL.md content
Level 3: Tools (loaded on activation)
└── Only activated skill's tools sent to model
API Design Options
Option 1: Declarative
agent = Agent(
model='openai:gpt-4',
skills=[
Skill.from_directory('./skills/excel'),
Skill.from_directory('./skills/pdf'),
],
)Option 2: Decorator
@agent.skill(trigger=['excel', 'spreadsheet'])
def excel_skill() -> str:
"""Excel file manipulation."""
return "## Excel Skill\nYou can read, write, and format Excel files..."
@excel_skill.tool
def read_excel(path: str) -> dict:
...Questions for Maintainers
-
Direction: Does this align with PydanticAI's roadmap? Are there similar features planned?
-
API Preference: Which API style do you prefer?
- Declarative (
skills=[...]) - Decorator (
@agent.skill) - Both?
- Declarative (
-
Integration Point: Should Skills be a core feature or an extension package?
-
Trigger Mechanism: Simple keyword matching vs LLM-based selection vs configurable?
I'm Willing to Contribute
If this direction is approved, I'm happy to:
- Submit a detailed RFC with implementation details
- Implement an MVP as a PR
- Write documentation and tests
References
- [Anthropic: Equipping agents for the real world with agent skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [LangChain Deep Agents](https://blog.langchain.dev/deep-agents/)
- [PydanticAI Documentation](https://ai.pydantic.dev/)
References
No response