There’s something slightly absurd about writing a skill that teaches Claude Code how to write skills. But here we are.
A quick note for readers who haven’t come across the concept: skills are SKILL.md files that extend Claude Code’s behavior for specific situations. Drop one into ~/.claude/skills/<name>/ and Claude picks it up automatically, activating when the right trigger conditions appear. I’ve come to think of them as the most important building block in my Claude Code setup: a lightweight way to encode repeatable workflows that would otherwise need to be re-explained from scratch in every session. The difference between having a skill for something and not having one is, in my experience, the difference between a tool that behaves consistently and one that improvises.
What I’ve also noticed is that most examples out there are fairly minimal. The frontmatter (the YAML block at the top of a SKILL.md) typically uses just name and description. But Claude Code supports a much richer set of fields: when_to_use, model, effort, allowed-tools, paths, argument-hint, disable-model-invocation, and more. Each one does something specific, and using them thoughtfully makes the difference between a skill that Claude occasionally notices and one that activates reliably and behaves exactly as intended.
So when I sat down to guide Claude through writing a skill about writing skills, I wanted to make sure we got all of that right.
The insight that started it
The key design decision came not from my own experimentation (I tried a few things that didn’t work before finding it) but from reading about Jesse Vincent’s superpowers framework in a review generated by a workflow I made, which I described in more detail here. The insight was this: when a skill’s description field summarises the workflow step by step, the agent reads the summary and follows that instead of reading the actual skill body. The description should carry only triggering conditions: the “when,” not the “what.” Everything else belongs in the body.
That single idea shaped the whole skill. It also explained why some of the skills I’d written earlier weren’t working as reliably as I expected (the description was doing too much).
What the skill looks like
Here’s the frontmatter for writing-skills itself:
--- name: writing-skills description: "Guides creation or update of a SKILL.md: chooses the right frontmatter fields, runs two pressure tests, and follows the approval flow before writing." when_to_use: "Use when asked to write, create, or update a skill (SKILL.md file). Follow all steps in order; do not shortcut based on this description." model: opus ---
A few things worth pointing out. The description is outcome-focused (what the skill produces), while when_to_use carries the trigger conditions and an explicit anti-shortcut note (“Follow all steps in order; do not shortcut based on this description”). The model: opus field tells Claude Code to use Opus for this skill, which makes sense for anything that involves judgment rather than mechanical execution. For skills that run repetitive shell commands, I add allowed-tools to avoid constant permission prompts. For skills I never want triggered accidentally (posting to a live site, for instance), disable-model-invocation: true acts as a deliberate gate.
The body follows the same logic: step-by-step, imperative, with explicit callouts wherever a lazy agent would otherwise cut corners. The pressure-test step near the end (where I ask what a lazy agent would do without the skill) has caught more gaps than I expected.
Where to find it
I’ve published writing-skills, along with a couple of other skills I use regularly (grill-me, which runs a structured design interview, and code-review), in a public repo at gsarig/skills. Each skill has its own folder and a README with installation instructions and attribution.
If you’ve been writing Claude Code skills and taken a different approach to the frontmatter, or run into the description-as-shortcut problem yourself, I’d be curious to hear how you handled it.