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[Any]

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 
 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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
class SkillsCapability(_AbstractCapabilityBase[Any]):
    """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) -> AgentInstructions[AgentDepsT] | None:
        """Return dynamic instructions via the underlying skills toolset.

        For pydantic-ai >= 1.74, instructions are natively extracted from the toolset
        by the agent, so we return None here to avoid injecting duplicate instructions.
        For older versions (pydantic-ai>=1.71), we return a function that delegates to the toolset.
        """
        try:
            from pydantic_ai.toolsets import AbstractToolset

            if hasattr(AbstractToolset, 'get_instructions'):
                return None
        except ImportError:
            pass

        async def _instructions(ctx: RunContext[AgentDepsT]) -> 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 
 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
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 
117
118
119
def get_toolset(self) -> SkillsToolset | None:
    """Return the underlying skills toolset."""
    return self._toolset

get_instructions 

get_instructions() -> AgentInstructions[AgentDepsT] | None

Return dynamic instructions via the underlying skills toolset.

For pydantic-ai >= 1.74, instructions are natively extracted from the toolset by the agent, so we return None here to avoid injecting duplicate instructions. For older versions (pydantic-ai>=1.71), we return a function that delegates to the toolset.

Source code in pydantic_ai_skills/capability.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def get_instructions(self) -> AgentInstructions[AgentDepsT] | None:
    """Return dynamic instructions via the underlying skills toolset.

    For pydantic-ai >= 1.74, instructions are natively extracted from the toolset
    by the agent, so we return None here to avoid injecting duplicate instructions.
    For older versions (pydantic-ai>=1.71), we return a function that delegates to the toolset.
    """
    try:
        from pydantic_ai.toolsets import AbstractToolset

        if hasattr(AbstractToolset, 'get_instructions'):
            return None
    except ImportError:
        pass

    async def _instructions(ctx: RunContext[AgentDepsT]) -> 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,
        )
    ],
)