SkillsCapability API Reference

SkillsCapability integrates pydantic-ai-skills with Pydantic AI's capabilities API.

This is the preferred integration path. Use it when your agent uses capabilities=[...].

Bases: AbstractCapability[Any]

Capability wrapper for SkillsToolset.

Use this class with the agent capabilities=[...] API.

Example

from pydantic_ai import Agent
from pydantic_ai_skills import SkillsCapability

agent = Agent(
    model='openai:gpt-5.2',
    capabilities=[SkillsCapability(directories=['./skills'])],
)

Source code in pydantic_ai_skills/capability.py

class SkillsCapability(AbstractCapability[Any]):
    """Capability wrapper for `SkillsToolset`.

    Use this class with the agent `capabilities=[...]` API.

    Example:
        ```python
        from pydantic_ai import Agent
        from pydantic_ai_skills import SkillsCapability

        agent = Agent(
            model='openai:gpt-5.2',
            capabilities=[SkillsCapability(directories=['./skills'])],
        )
        ```
    """

    def __init__(
        self,
        *,
        skills: list[Skill] | None = None,
        directories: list[str | Path | SkillsDirectory] | None = None,
        registries: list[SkillRegistry] | None = None,
        validate: bool = True,
        max_depth: int | None = 3,
        id: str | None = None,
        instruction_template: str | None = None,
        exclude_tools: set[str] | list[str] | None = None,
        auto_reload: bool = False,
    ) -> None:
        """Initialize a skills capability.

        Args:
            skills: Pre-loaded skills.
            directories: Skill directories to discover.
            registries: Remote registries to discover.
            validate: Validate skill structure during discovery.
            max_depth: Maximum discovery depth.
            id: Optional toolset id.
            instruction_template: Optional custom instructions template.
            exclude_tools: Tool names to exclude.
            auto_reload: Re-scan directories before each run.
        """
        self._toolset = SkillsToolset(
            skills=skills,
            directories=directories,
            registries=registries,
            validate=validate,
            max_depth=max_depth,
            id=id,
            instruction_template=instruction_template,
            exclude_tools=exclude_tools,
            auto_reload=auto_reload,
        )

    def get_toolset(self) -> SkillsToolset | None:
        """Return the underlying skills toolset."""
        return self._toolset

    def get_instructions(self) -> AgentInstructions[AgentDepsT] | None:
        """Return None — instructions are pulled natively from the toolset by the agent."""
        return None

    @property
    def toolset(self) -> SkillsToolset:
        """Expose the underlying `SkillsToolset` instance."""
        return self._toolset

__init__

__init__(*, skills: list[Skill] | None = None, directories: list[str | Path | SkillsDirectory] | None = None, registries: list[SkillRegistry] | None = None, validate: bool = True, max_depth: int | None = 3, id: str | None = None, instruction_template: str | None = None, exclude_tools: set[str] | list[str] | None = None, auto_reload: bool = False) -> None

Initialize a skills capability.

Parameters:

Name	Type	Description	Default
skills	list[Skill] | None	Pre-loaded skills.	None
directories	list[str | Path | SkillsDirectory] | None	Skill directories to discover.	None
registries	list[SkillRegistry] | None	Remote registries to discover.	None
validate	bool	Validate skill structure during discovery.	True
max_depth	int | None	Maximum discovery depth.	3
id	str | None	Optional toolset id.	None
instruction_template	str | None	Optional custom instructions template.	None
exclude_tools	set[str] | list[str] | None	Tool names to exclude.	None
auto_reload	bool	Re-scan directories before each run.	False

Source code in pydantic_ai_skills/capability.py

def __init__(
    self,
    *,
    skills: list[Skill] | None = None,
    directories: list[str | Path | SkillsDirectory] | None = None,
    registries: list[SkillRegistry] | None = None,
    validate: bool = True,
    max_depth: int | None = 3,
    id: str | None = None,
    instruction_template: str | None = None,
    exclude_tools: set[str] | list[str] | None = None,
    auto_reload: bool = False,
) -> None:
    """Initialize a skills capability.

    Args:
        skills: Pre-loaded skills.
        directories: Skill directories to discover.
        registries: Remote registries to discover.
        validate: Validate skill structure during discovery.
        max_depth: Maximum discovery depth.
        id: Optional toolset id.
        instruction_template: Optional custom instructions template.
        exclude_tools: Tool names to exclude.
        auto_reload: Re-scan directories before each run.
    """
    self._toolset = SkillsToolset(
        skills=skills,
        directories=directories,
        registries=registries,
        validate=validate,
        max_depth=max_depth,
        id=id,
        instruction_template=instruction_template,
        exclude_tools=exclude_tools,
        auto_reload=auto_reload,
    )

get_toolset

get_toolset() -> SkillsToolset | None

Return the underlying skills toolset.

Source code in pydantic_ai_skills/capability.py

def get_toolset(self) -> SkillsToolset | None:
    """Return the underlying skills toolset."""
    return self._toolset

get_instructions

get_instructions() -> AgentInstructions[AgentDepsT] | None

Return None — instructions are pulled natively from the toolset by the agent.

Source code in pydantic_ai_skills/capability.py

def get_instructions(self) -> AgentInstructions[AgentDepsT] | None:
    """Return None — instructions are pulled natively from the toolset by the agent."""
    return None

toolset property

toolset: SkillsToolset

Expose the underlying SkillsToolset instance.

Constructor Parameters

SkillsCapability.__init__() accepts the same skill loading options as SkillsToolset:

Parameter	Type	Default	Description
skills	list[Skill] \| None	None	Pre-loaded Skill objects.
directories	list[str \| Path \| SkillsDirectory] \| None	None	Local skill sources.
registries	list[SkillRegistry] \| None	None	Remote skill sources.
validate	bool	True	Validate discovered skills.
max_depth	int \| None	3	Directory discovery depth.
id	str \| None	None	Optional toolset id.
instruction_template	str \| None	None	Optional custom instruction template.
exclude_tools	set[str] \| list[str] \| None	None	Exclude one or more registered tools.
auto_reload	bool	False	Re-scan local directories before each run.

Behavior Notes

• Internally wraps a SkillsToolset for behavior parity.
• get_toolset() and .toolset expose the wrapped SkillsToolset instance.
• Bundles skill tools and skills instructions through the Capability API.
• Avoids manual @agent.instructions wiring for get_instructions(ctx).
• Raises RuntimeError at instantiation time if capabilities API is unavailable.

Example

from pydantic_ai import Agent
from pydantic_ai_skills import SkillsCapability

agent = Agent(
    model='openai:gpt-5.2',
    capabilities=[
        SkillsCapability(
            directories=['./skills'],
            auto_reload=True,
        )
    ],
)