pydantic-ai-skills

The data-analysis skill allows an agent to profile and aggregate a bundled sales dataset (resources/sales.csv). It is designed to be used in sandboxed environments as it relies only on the Python standard library and requires no network access.

Use this skill to answer questions regarding:

• Sales figures and trends.
• Segment performance (e.g., which region or category performs best).
• Summary statistics of the dataset.

A registry is an abstraction for a source of skill libraries. Its purpose is to fetch Agent Skill packages from a remote or local source and materialize them into a local directory that the SkillsCapability can use.

All registries implement a single idempotent sync() method. Calling sync() refreshes the local copy (e.g., via git pull or S3 re-sync) rather than starting from scratch. Registries are responsible for fetching and materializing files, but they do not parse SKILL.md files; validation and rendering are handled by the harness.

class SkillRegistry(ABC):
    @abstractmethod
    def sync(self) -> Path:
        """Materialize the skills and return the local library directory."""

A Toolset is a collection of tools that can be registered with an agent in a single step. Unlike individual tools, toolsets are designed for reuse across multiple agents, dynamic composition, and advanced management like prefixing or filtering.

Agent Skills follow a progressive disclosure model to save prompt space:

1. Discovery: The agent initially only sees the name and description of each skill in its catalog.
2. Loading: When a task requires a specific skill, Pydantic AI uses load_capability to fetch the full Markdown instructions.
3. Execution: Once loaded, the agent can access bundled files or scripts using the tools provided by pydantic-ai-skills.

This allows your skill library to grow significantly without bloating the agent's context window.

Skills are organized into libraries. When using them, you must pass the library path to the capability, not an individual skill package. Note that the search is not recursive; for example, if you pass skills/, it will find immediate children like skills/web-research/, but it will not find skills/research/arxiv-search/.

Bundled Libraries in Examples

Use pydantic-ai-harness if your skills are only instructions and you want a smaller dependency.

Use pydantic-ai-skills if you need:

• Remote registries (Git, S3).
• Bundled file access (read_skill_resource, run_skill_script).
• Sandboxed execution for untrusted scripts.
• ${SKILL_DIR} resolution.
• Programmatic skills (defined in Python).

Pydantic AI provides tools to access and manage the full conversation history of an agent run. You can distinguish between the entire conversation context and only the messages generated during a specific run. This allows for building multi-turn conversations and managing context window limits.

Key methods on the result object:

• result.all_messages(): Returns all messages, including any prior history that was passed into the run.
• result.new_messages(): Returns only the messages produced during the current run. Use this method to chain consecutive runs together.

Pydantic AI uses a first-class dependency injection system to pass strongly typed data and services (like API clients or configuration) to tools, system prompts, and output validators.

To use dependencies:

1. Define a dependency container (e.g., a @dataclass).
2. Register the dependency type on the Agent constructor using the deps_type parameter (pass the class, not an instance).
3. Access the injected values within your functions using RunContext[T]. The injected instance is available via ctx.deps.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class MyDeps:
    api_key: str

# Register the type via deps_type
agent = Agent('openai:gpt-4o', deps_type=MyDeps)

@agent.tool
async def my_tool(ctx: RunContext[MyDeps]) -> str:
    # Access the instance via ctx.deps
    return f"Using key: {ctx.deps.api_key}"

In Pydantic AI, an MCP server instance acts as a toolset. You can register one or more MCP servers as toolsets when initializing an Agent.

To ensure the connection lifecycle is managed correctly (opening and closing connections to the servers), you must use the async with agent: context manager before running agent tasks.

Composition wrappers allow you to create new, specialized registries by wrapping an existing one. The wrapper syncs the underlying registry and then stages a new library containing only the selected packages under specific names. The original wrapped registry remains unmodified.

Available wrappers:

• FilteredRegistry: Includes only skills that match specific criteria.
• PrefixedRegistry: Adds a prefix to the names of the skills.
• RenamedRegistry: Maps existing skill names to new names.
• CombinedRegistry: Merges multiple registries into one.