#3780 Introduce support for agent skills

• Closes https://github.com/pydantic/pydantic-ai/issues/3781

This pull request introduces a new "Skills" system to Pydantic AI, enabling modular, progressive skill discovery and execution for agents. The main changes include the addition of the SkillsToolset and related types, updates to documentation and examples to demonstrate skill usage, and new skill definitions and scripts for practical use.

Warning! The pyYAML dependency was added to pydantic-ai-slim because Agent Skills uses YAML frontmatter to structure skill metadata.

References:

• DougTrajano/pydantic-ai-skills
• vstorm-co/pydantic-deepagents

Skills Toolset Integration

• Added SkillsToolset and supporting types (Skill, SkillMetadata, SkillResource, SkillScript, etc.) to the main package exports, enabling agents to discover and use skills dynamically. [1] [2] [3] [4] [5]
• Created pydantic_ai/toolsets/skills/__init__.py with documentation and examples for building and managing agent skills.

Documentation and API Reference Updates

• Updated API docs (docs/api/toolsets.md) and navigation (mkdocs.yml) to include the new Skills toolset and its members, ensuring clear guidance for users. [1] [2]
• Added a comprehensive skill documentation example for Pydantic AI (pydanticai-docs/SKILL.md), detailing framework features and usage patterns.

Skill Example Implementation

• Added an example skill for searching arXiv (arxiv-search/SKILL.md and arxiv_search.py), including usage instructions, argument descriptions, and output formatting. [1] [2]

Agent Example with Skills

• Provided a new example (skills_agent.py) demonstrating how to create an agent with skills, list available skills, load instructions, and execute skill scripts.

These changes collectively enable agents to leverage domain-specific skills, improve extensibility, and provide clear documentation and examples to help users get started.