Skip to content

SkillsCapability API Reference

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

For pydantic-ai >= 1.71, this is the preferred integration path.

Use this when your agent uses capabilities=[...].

Bases: _AbstractCapabilityBase[AgentDepsT]

Capability wrapper for SkillsToolset.

Use this class with the agent capabilities=[...] API introduced in pydantic-ai 1.71+.

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 
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
class SkillsCapability(_AbstractCapabilityBase[AgentDepsT]):
    """Capability wrapper for `SkillsToolset`.

    Use this class with the agent `capabilities=[...]` API introduced in
    pydantic-ai 1.71+.

    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.

        Raises:
            RuntimeError: If capabilities API is unavailable in installed
                pydantic-ai version.
        """
        if not _CAPABILITIES_AVAILABLE:
            raise RuntimeError(
                'SkillsCapability requires pydantic-ai>=1.71 with capabilities support. '
                'Use SkillsToolset instead or upgrade pydantic-ai.'
            )

        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) -> Any:
        """Return dynamic instructions via the underlying skills toolset."""

        async def _instructions(ctx: RunContext[Any]) -> str | None:
            return await self._toolset.get_instructions(ctx)

        return _instructions

    @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

Raises:

Type Description
RuntimeError

If capabilities API is unavailable in installed pydantic-ai version.
Source code in pydantic_ai_skills/capability.py 
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
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.

    Raises:
        RuntimeError: If capabilities API is unavailable in installed
            pydantic-ai version.
    """
    if not _CAPABILITIES_AVAILABLE:
        raise RuntimeError(
            'SkillsCapability requires pydantic-ai>=1.71 with capabilities support. '
            'Use SkillsToolset instead or upgrade pydantic-ai.'
        )

    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 
102
103
104
def get_toolset(self) -> SkillsToolset | None:
    """Return the underlying skills toolset."""
    return self._toolset

get_instructions 

get_instructions() -> Any

Return dynamic instructions via the underlying skills toolset.

Source code in pydantic_ai_skills/capability.py 
106
107
108
109
110
111
112
def get_instructions(self) -> Any:
    """Return dynamic instructions via the underlying skills toolset."""

    async def _instructions(ctx: RunContext[Any]) -> str | None:
        return await self._toolset.get_instructions(ctx)

    return _instructions

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,
        )
    ],
)