write-a-skill

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• write a skill
• create a new Claude Code skill
• package this as a skill

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. 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. Canonical SKILL.md lives in the write-a-skill folder 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.