Skills

---
name: refund-policy
description: The shop's refund rules. Use when a customer asks what can be refunded.
---

Say exactly: Refunds run for 14 days from delivery, minus return postage.

try:
    flags(ClaudeAgentOptions(skills=["shop:*"]))
except ValueError as error:
    print(error)

Invalid skill name 'shop:*': wildcard-suffix names are not allowed; list each skill by its exact name.

    def roots(self):
        """The folders a skill can come from, each with the prefix its names carry."""
        found = []
        if "project" in self.sources():
            # cwd plus every add_dirs entry, which the SDK hands over as --add-dir
            where = [self.options.cwd or "."] + list(self.options.add_dirs)
            found += [(Path(d) / ".claude", "") for d in where]

        if "user" in self.sources():
            found.append((Path.home() / ".claude", ""))
        return found

    def find_skills(self):
        """name -> SKILL.md text, for every skill folder this session loads."""
        return {prefix + path.parent.name: path.read_text()
                for root, prefix in self.roots()
                for path in sorted(root.glob("skills/*/SKILL.md"))}

    def permitted(self):
        """The skills Claude may invoke: the skills option filters what was discovered."""
        # the one place the option decides anything; discovery above it is untouched
        chosen = self.options.skills
        if chosen is None or chosen == "all":
            return dict(self.found)
        return {name: body for name, body in self.found.items() if name in chosen}

    def offered(self):
        """What the model may call: the MCP tools, plus Skill when a skill is permitted."""
        return list(self.tools) + (["Skill"] if self.permitted() else [])

    def run_skill(self, name):
        # a skill the list leaves out is refused here, not hidden from the filesystem
        if name not in self.permitted():
            return f"Skill {name} is not in this session's skills allowlist"
        return self.follow(self.found[name])

    def follow(self, body, args=""):
        """The desk obeys one instruction shape; a real model reads the whole body."""
        # everything after the frontmatter is the instruction
        text = body.split("---", 2)[-1].strip()

        for line in text.splitlines():
            if line.lower().startswith("say exactly:"):
                text = line.split(":", 1)[1].strip()
                break
        return text.replace("$ARGUMENTS", args).strip()

        # discovery happens at session start, which is why the init message can list it
        self.found = self.find_skills()
        await self.send({"type": "system", "subtype": "init", "model": "shop-desk",
                         "session_id": self.session_id, "tools": list(self.tools),
                         "skills": sorted(self.found)})

        # Skill reads a file this session already loaded, so no server is called for it
        if name == "Skill":
            text, failed = self.run_skill(args["name"]), False
        else:

    def reply(self, said, results, tools=(), rules="", skills=()):
        ...
        # the stand-in matches a skill on the words in its name, where Claude reads its description
        for name in skills:
            if any(word in said[-1].lower() for word in name.split(":")[-1].split("-")):
                return {"calls": [("Skill", {"name": name})]}

        self.tools, self.failed, self.ready = {}, None, False
        self.found, self.loaded = {}, []

await watch("What is the refund policy?", desk(["refund-policy"]))

system     init
assistant  calls Skill {'name': 'refund-policy'}
user       result: Refunds run for 14 days from delivery, minus return postage.
assistant  Refunds run for 14 days from delivery, minus return postage.
result     success: Refunds run for 14 days from delivery, minus return postage.

await watch("What is the refund policy?", desk([]))

system     init
assistant  Which order is this about?
result     success: Which order is this about?

from claude_agent_sdk import SystemMessage, query
from shop_desk import ShopDesk

options = desk(["refund-policy"])
async for message in query(prompt="Hello", options=options, transport=ShopDesk(options)):
    if isinstance(message, SystemMessage) and message.subtype == "init":
        print(message.data["skills"])

['refund-policy']

from shop_desk import ShopModel

script = [{"calls": [("Skill", {"name": "refund-policy"})]}]
await watch("What is the refund policy?", desk(["order-status"]), ShopModel(script))

system     init
assistant  calls Skill {'name': 'refund-policy'}
user       result: Skill refund-policy is not in this session's skills allowlist
assistant  Skill refund-policy is not in this session's skills allowlist
result     success: Skill refund-policy is not in this session's skills allowlist