06 — Skills — Teaching the Loop Repeatable Workflows On Demand

"Just saved prompts" was my read on skills, and it missed the loading mechanism that makes them work. The distinction that stuck: a skill is a folder of expert knowledge and repeatable workflow that Claude loads dynamically into context only when the task requires it — not a script that always runs. [1] The whole point is lazy loading: the skill sits dormant until its description matches what I'm doing, and only then does it enter the context window.

The framing that clicked is the contrast with CLAUDE.md. The memory file loads at _every_ launch, so it has to stay short. A skill loads _on demand_, so it can be deep — a full deployment runbook, a security-audit procedure, a multi-step content workflow — without taxing sessions that don't need it [1][2]. That separation is what makes the system scale: persistent rules in the memory file, deep procedural knowledge in skills, and never the two bloating each other.

The anatomy of a skill

Mechanically, a skill is a folder inside .claude/skills/ anchored by a SKILL.md file [1]. The file has two parts:

• YAML frontmatter — at minimum a unique name and a detailed description. This frontmatter is what Claude reads to decide whether the skill is relevant; the description is the semantic trigger.
• A body of specific instructions — the actual workflow: which tools to call, in what order, against what inputs.

The detail that made it click: Claude never reads the body until the description matches. The frontmatter is the index; the body is the payload. A poorly-written description means the skill never fires (or fires when it shouldn't); a well-written one means the right deep instructions show up exactly when needed. The roadmap is blunt that the description is the leverage point — it should use specific keywords that help Claude identify when to activate the expert instructions without bloating every conversation [2].

Creating a custom skill

The recipe from the roadmap is concrete [3]: establish a folder in .claude/skills/ containing a SKILL.md. The frontmatter block holds the unique name and the detailed description (the trigger), and the body holds the logic. Two optional knobs matter:

• disable-model-invocation: true — flips the skill from autonomous to manual. With this set, Claude won't auto-load it on a description match; it only runs when I trigger it explicitly via a slash command. This is the right choice for workflows with non-negotiable side effects — a deploy, a destructive migration — where I want determinism, not a model's judgement call [2].
• Argument placeholders like $ARGUMENTS — make the skill reusable across different files. A "create-blog" skill can take a topic as an argument instead of being hard-coded.

The body should be a narrow, modular workflow rather than a "Swiss Army Knife" skill. If I have a deployment procedure and a security audit, those are two skills, not one — because their descriptions need to match different tasks precisely. And skills belong in the project's .claude/skills/ so they're version-controlled and shared with the team [2].

Skill best practices

The roadmap collects the discipline into a short list that matches what I've seen work [2]:

• Optimize for discoverability. The description is a semantic trigger — use specific keywords. Vague descriptions mean the skill never fires.
• Lazy-load. The whole architecture exists to keep idle skills out of context. Respect it: don't dump every skill into the memory file.
• Keep skills modular and narrow. One workflow per skill. A "do everything" skill defeats discovery.
• Use disable-model-invocation for side effects. Deploys, migrations, anything destructive — make it manual.
• Make instructions deterministic. Provide step-by-step tool sequences so Claude follows the project's golden path for complex tasks, rather than improvising.
• Version-control them. .claude/skills/ goes in git so the whole team shares the same workflows.

How I use this

The habit these notes left me with is a simple test for when something becomes a skill: do I do this workflow more than twice, and does it have more than three steps? If yes, it earns a folder. The deploy runbook, the blog-creation procedure, the security scan — each lives in its own skill with a precise description and a deterministic body. Side-effect-heavy ones get disable-model-invocation: true. And I resist the urge to put rules in skills — rules go in CLAUDE.md because they apply to every session; skills are for procedures that apply to specific tasks on demand.

References

[1] Anthropic, "Extend Claude with skills," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/skills

[2] Anthropic, "The Complete Guide to Building Skills for Claude," Anthropic Resources, 2025. [Online]. Available: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en

[3] Anthropic, "How to create custom Skills," Claude Support, 2025. [Online]. Available: https://support.claude.com/en/articles/12512198-how-to-create-custom-skills