Skip to content

UseSkillTool

Tools for Skills activation.

UseSkillTool

Bases: BaseTool

A dedicated tool for activating a skill.

Attributes:

Name Type Description
skills dict[str, Skill]

All discovered skills, keyed by name. Skills in explicit_only_skills are excluded from the enum but remain loadable if called directly via run_with_skill().
Source code in src/llm_agents_from_scratch/skills/tools.py 
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 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
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
145
class UseSkillTool(BaseTool):
    """A dedicated tool for activating a skill.

    Attributes:
        skills (dict[str, Skill]): All discovered skills, keyed by name.
            Skills in ``explicit_only_skills`` are excluded from the enum
            but remain loadable if called directly via ``run_with_skill()``.
    """

    def __init__(
        self,
        skills: dict[str, Skill],
        explicit_only_skills: set[str] | None = None,
    ) -> None:
        """Initialize a UseSkillTool.

        Args:
            skills (dict[str, Skill]): All discovered skills, keyed by name.
            explicit_only_skills (set[str] | None): Skill names excluded from
                the model-visible catalog. They remain loadable via
                ``run_with_skill()``. Defaults to None.
        """
        self._skills = skills
        self._explicit_only_skills = explicit_only_skills or set()
        self._visible = [
            name for name in skills if name not in self._explicit_only_skills
        ]

    @property
    def name(self) -> str:
        """Name of skill activation tool."""
        return "from_scratch__use_skill"

    @property
    def description(self) -> str:
        """Description of the skill activation tool."""
        return (
            "Load and activate a skill by name, returning its full"
            " instructions. Only call this tool with a skill name from"
            " the <available_skills> catalog."
        )

    @property
    def parameters_json_schema(self) -> dict[str, Any]:
        """JSON schema for tool parameters.

        The ``name`` field is constrained to an enum of visible skill names
        (i.e. skills that have not set ``disable-model-invocation``).
        """
        return {
            "type": "object",
            "properties": {
                "name": {"type": "string", "enum": self._visible},
            },
            "required": ["name"],
        }

    def _build_skill_content(self, name: str) -> str:
        """Build the ``<skill_content>`` block for a skill.

        Args:
            name: The skill name to build content for.

        Returns:
            Formatted ``<skill_content>`` XML string.
        """
        skill = self._skills[name]
        resources = skill.resources
        skill_resources = (
            SKILL_RESOURCES_TEMPLATE.format(
                files="\n".join(
                    f"  <file>{r.as_posix()}</file>" for r in resources
                ),
            )
            if resources
            else ""
        )
        return ACTIVATION_CONTENT_TEMPLATE.format(
            name=skill.frontmatter.name,
            body=skill.read_body(),
            skill_dir=skill.location.parent.as_posix(),
            skill_resources=skill_resources,
        )

    def __call__(
        self,
        tool_call: ToolCall,
        *args: Any,
        **kwargs: Any,
    ) -> ToolCallResult:
        """Execute the skill activation tool.

        Args:
            tool_call (ToolCall): The ToolCall to execute.
            *args (Any): Additional positional arguments.
            **kwargs (Any): Additional keyword arguments.

        Returns:
            ToolCallResult: The activated skill's full content.
        """
        # Validate only that "name" is a present string, not the enum.
        # parameters_json_schema is narrower — it only enumerates visible
        # (non-explicit-only) skills as a hint to the model. Explicit-only
        # skills are absent from that enum but must still be activatable here.
        skill_name = tool_call.arguments.get("name")
        if not isinstance(skill_name, str):
            return ToolCallResult(
                tool_call_id=tool_call.id_,
                content=json.dumps(
                    {
                        "error_type": "ValueError",
                        "message": "'name' argument must be a string.",
                    },
                ),
                error=True,
            )
        if skill_name not in self._skills:
            return ToolCallResult(
                tool_call_id=tool_call.id_,
                content=json.dumps(
                    {
                        "error_type": "ValueError",
                        "message": f"Skill '{skill_name}' not found.",
                    },
                ),
                error=True,
            )
        content = self._build_skill_content(skill_name)

        return ToolCallResult(
            tool_call_id=tool_call.id_,
            content=content,
            error=False,
        )

name property 

name

Name of skill activation tool.

description property 

description

Description of the skill activation tool.

parameters_json_schema property 

parameters_json_schema

JSON schema for tool parameters.

The name field is constrained to an enum of visible skill names (i.e. skills that have not set disable-model-invocation).

__init__ 

__init__(skills, explicit_only_skills=None)

Initialize a UseSkillTool.

Parameters:

Name Type Description Default
skills dict[str, Skill]

All discovered skills, keyed by name.

 required
explicit_only_skills set[str] | None

Skill names excluded from the model-visible catalog. They remain loadable via run_with_skill(). Defaults to None.

 None
Source code in src/llm_agents_from_scratch/skills/tools.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
def __init__(
    self,
    skills: dict[str, Skill],
    explicit_only_skills: set[str] | None = None,
) -> None:
    """Initialize a UseSkillTool.

    Args:
        skills (dict[str, Skill]): All discovered skills, keyed by name.
        explicit_only_skills (set[str] | None): Skill names excluded from
            the model-visible catalog. They remain loadable via
            ``run_with_skill()``. Defaults to None.
    """
    self._skills = skills
    self._explicit_only_skills = explicit_only_skills or set()
    self._visible = [
        name for name in skills if name not in self._explicit_only_skills
    ]

__call__ 

__call__(tool_call, *args, **kwargs)

Execute the skill activation tool.

Parameters:

Name Type Description Default
tool_call ToolCall

The ToolCall to execute.

 required
*args Any

Additional positional arguments.

 ()
**kwargs Any

Additional keyword arguments.

 {}

Returns:

Name Type Description
ToolCallResult ToolCallResult

The activated skill's full content.
Source code in src/llm_agents_from_scratch/skills/tools.py 
 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
145
def __call__(
    self,
    tool_call: ToolCall,
    *args: Any,
    **kwargs: Any,
) -> ToolCallResult:
    """Execute the skill activation tool.

    Args:
        tool_call (ToolCall): The ToolCall to execute.
        *args (Any): Additional positional arguments.
        **kwargs (Any): Additional keyword arguments.

    Returns:
        ToolCallResult: The activated skill's full content.
    """
    # Validate only that "name" is a present string, not the enum.
    # parameters_json_schema is narrower — it only enumerates visible
    # (non-explicit-only) skills as a hint to the model. Explicit-only
    # skills are absent from that enum but must still be activatable here.
    skill_name = tool_call.arguments.get("name")
    if not isinstance(skill_name, str):
        return ToolCallResult(
            tool_call_id=tool_call.id_,
            content=json.dumps(
                {
                    "error_type": "ValueError",
                    "message": "'name' argument must be a string.",
                },
            ),
            error=True,
        )
    if skill_name not in self._skills:
        return ToolCallResult(
            tool_call_id=tool_call.id_,
            content=json.dumps(
                {
                    "error_type": "ValueError",
                    "message": f"Skill '{skill_name}' not found.",
                },
            ),
            error=True,
        )
    content = self._build_skill_content(skill_name)

    return ToolCallResult(
        tool_call_id=tool_call.id_,
        content=content,
        error=False,
    )