Write a reusable AI agent skill

Why it holds

The same class is added twice here with different params, so one skill serves two locations without being copied.

How it works

A SkillBase subclass declares a name and fills in three contributions.

class StoreHoursSkill(SkillBase):
    SKILL_NAME = "store_hours"
    SUPPORTS_MULTIPLE_INSTANCES = True

    def setup(self):        # validated before the agent is served
    def get_hints(self):    # words the recogniser would guess at
    def _get_prompt_sections(self):   # what the model is told
    def register_tools(self):         # the tools themselves

setup() returns a boolean, and returning False stops the skill loading. A skill that cannot work should say so at startup rather than mid-call.

register_tools uses self.define_tool, not self.agent.define_tool. The wrapper merges the skill’s swaig_fields into every tool it registers, which is how a caller of the skill sets things like secure once for all of them.

To make your own class addressable by name, register it:

skill_registry.register_skill(StoreHoursSkill)
agent.add_skill("store_hours", {"tool_name": "shop_hours", ...})

add_skill_directory() is the other route, for a directory of skills laid out like the built-in ones.

The multi-instance rule is worth reading twice. The instance key is SKILL_NAME plus params["tool_name"], so two instances need distinct tool names. Add the same skill twice without them and the second is dropped with a warning in the log and no error anywhere. The tool the model sees is named from the same value, which is also what stops the two tools colliding.

Limitations

Skills compose tools, not conversations. Two skills that both want to own the greeting will fight over the prompt, and nothing arbitrates that for you.

SUPPORTS_MULTIPLE_INSTANCES is opt-in and defaults to false. A skill written without it cannot be added twice, and the failure is a log line.