# write-a-skill

> A meta Claude Code skill that creates new skills with proper structure, frontmatter, and trigger-rich descriptions following the SKILL.md / progressive-disclosure format. Useful for packaging your own skills or skill packs.

**Use case**: Create new Claude Code skills, including ones intended for sale or distribution

**Canonical URL**: https://agentcookbooks.com/skills/write-a-skill/

**Topics**: claude-code, skills, skill-development

**Trigger phrases**: "write a skill", "create a new Claude Code skill", "package this as a skill"

**Source**: [Matt Pocock](https://github.com/mattpocock/skills/tree/main/write-a-skill)

**License**: MIT

---

## What it does

`write-a-skill` is the skill that builds skills. Given a workflow you already run manually or want to formalize, it produces a properly-structured SKILL.md with:

- Trigger-rich description (the part that determines when the skill activates)
- Progressive disclosure of detail (instructions vs reference vs examples)
- Frontmatter that follows the conventions Claude Code expects
- Optional supporting files (templates, scripts) if the skill needs them

It's a forcing function for thinking through *when* a skill should fire and *what* it should expand into — the two parts that tend to be sloppy when people roll their own.

## When to use it

- You've found yourself repeating the same prompt structure 3+ times → it's time to package it
- You're building a skill pack to sell or distribute
- You're refactoring a long, sloppy skill into something cleaner
- You're writing your first skill and want the format right from the start

When *not* to reach for it:

- A one-off prompt you'll use once — overhead exceeds value
- A workflow that hasn't stabilized yet — wait until the pattern is clear before formalizing
- Something that's actually a hook or an MCP server, not a skill — different tool

## Install

Distributed via Pocock's [skills repo](https://github.com/mattpocock/skills). Install via his recommended path (`npx skills add` or manual copy of SKILL.md into `.claude/skills/write-a-skill/`).

## What a session looks like

A typical session has three phases:

1. **You describe the workflow.** "Every time I do X, I follow these steps..." or paste an example prompt you'd use.
2. **The skill asks targeted questions** about: when should it fire (trigger phrases), what should it know, what should it produce, and where the line between instructions and reference material falls.
3. **It outputs a SKILL.md** with the right frontmatter, structured body, and any supporting files — ready to drop into `.claude/skills/<name>/`.

The discipline that makes it work: it forces you to write a *trigger-rich description*, not a vague summary. The description is what determines whether your skill activates when it should.

## Receipts

**Where it works well:**
- Surfaces ambiguity in your trigger conditions ("does this fire on every commit, or just commits to main?")
- Produces frontmatter you'd otherwise get wrong on a first try
- Naturally enforces progressive disclosure — instructions stay short, references go in supporting files

**Where it backfires:**
- If your workflow isn't stable, you'll write a skill, then immediately rewrite it. Wait until the workflow has actually run a few times.
- The skill can over-decompose a simple workflow into too many supporting files. Push back when this happens.
- For genuinely complex skills (orchestration, multi-step), expect to iterate after the first draft.

**Pattern that works:** wait for a workflow to repeat 3–5 times manually before invoking `write-a-skill` to formalize it. That's enough to know the trigger conditions, the inputs, and the outputs precisely.

## Source and attribution

Originally written by [Matt Pocock](https://github.com/mattpocock). Canonical SKILL.md lives in the [`write-a-skill` folder](https://github.com/mattpocock/skills/tree/main/write-a-skill) of his public skills repository.

License: MIT. Install, adapt, redistribute with attribution preserved.

For the formal spec and any updates, defer to the source repo.