Create a skill from scratch

A skill packages instructions so a model pulls them in only when a request actually matches, instead of you pasting the same paragraph into every conversation. You write it once: a short name, a description that states exactly when it applies, and the instructions themselves. The name and description sit in front of the model cheaply, all the time. The instructions load only once a request matches the description. This walks through building one from scratch: spotting the repeated task, writing a description sharp enough to trigger on the right requests, writing the instructions, bundling any scripts or reference files it needs, keeping it narrow, and testing it before you trust it.

1. Spot a task you repeat

Skills earn their keep on repetition, not on being clever. If you have explained the same review checklist, the same commit-message format, or the same "how we structure this kind of report" three times this month, in nearly the same words each time, that is a skill waiting to be written. A task you have only done once does not have enough pattern in it yet, you do not actually know what the reusable part is until you have hit it a second or third time and noticed what stays the same across attempts. Write down, in one sentence, what the task is and what "done" looks like. That sentence becomes the seed for the description you write next, so make it precise now instead of vague.

2. Write a name and description that state exactly when it applies

The description is the trigger, not a summary. Along with the skill's name, it is what the model sees before deciding whether the skill is relevant, so it has to name both what the skill does and the specific situations that should fire it. Anthropic's docs are direct about this: the description is what Claude matches a request against when deciding whether to trigger the skill, and it has to say both what the skill does and when to use it.² "Helps with documents" gives the model nothing to act on. A description that names the task and the trigger words a real request would contain gives it something to match against. Write it in the third person, describing what the skill does, not addressing the user directly, since the description gets read as part of the model's own instructions, not as a message to a person.

---
name: changelog-formatting
description: >
  Turns a list of raw commit messages into a formatted changelog
  entry with grouped sections and plain-language summaries. Use when
  the user pastes commit logs or asks for release notes, a changelog
  entry, or a "what changed" summary.
---

# Changelog Formatting

## Steps
1. Group commits into Added / Fixed / Changed
2. Drop merge commits and version bumps
3. Rewrite each line in plain language, present tense
4. Order sections: Added, Changed, Fixed

3. Write the instructions the skill injects

The instructions are what actually loads once the description matches, so they only need to cover what the model does not already know: your specific steps, your specific format, the one rule you always end up repeating. Anthropic's authoring guidance is blunt about this: assume the model is already smart, and challenge every paragraph with whether it justifies its token cost.² A paragraph explaining what a changelog is wastes space on something the model already knows; a paragraph naming your exact section order and your rule about dropping merge commits is the part only you know. Write it as a short, ordered set of steps wherever the task has a real sequence, and keep the whole file short enough that loading it never costs more than the problem is worth.

• The exact steps, in order, if the task has a real sequence, a numbered list beats a paragraph of prose.
• One concrete example of input and output, if the format matters more than a description alone can convey.
• The one rule you always repeat and always forget to mention until someone gets it wrong.
• Links to reference files or scripts for anything long or exact, rather than pasting it into the main instructions.

4. Bundle any scripts or reference files it needs

Not everything belongs in the main instructions. A skill can point to extra files, a longer reference document, a template, a script that runs a deterministic check, and the model only opens them when the task actually calls for them. This is what Anthropic's docs call progressive disclosure: the name and description load always, the main instructions load once the skill triggers, and anything bundled beyond that loads only when the instructions reference it.¹ That structure is also why a skill can carry a lot of material without costing much, a script that validates a format, an exact template, a long lookup table, none of it enters context until the task actually needs it.

5. Keep it narrowly scoped: one skill, one job

A skill that tries to cover five loosely related tasks ends up with a description too vague to trigger reliably on any of them, and instructions too long for any single use. Split it instead: one skill for formatting a changelog, a separate one for writing a commit message, a separate one for drafting a release announcement, even though all three touch "release." Each gets a description specific enough to match cleanly, and each stays short enough to load without dragging in guidance the current task does not need. If you find yourself writing "and also" in the description, that is usually the seam where the file should split into two.

6. Test that it triggers on the right requests and not the wrong ones, then tighten the description

A skill you have not tested is a guess about how the model reads your description, and guesses are usually wrong in a specific direction: too broad, so it fires on requests it should not, or too narrow, so it stays silent on requests it should have caught. Anthropic's authoring guidance recommends building a handful of real test requests before trusting a skill,² not just the one that inspired it. Run at least three: a request that should obviously trigger it, a near-miss that is adjacent but should not, and a request that names the general topic without needing this specific skill. Watch what actually happens, then edit the description first, not the instructions, to fix the misses.

1. 1Send a request that clearly matches the task. Confirm the skill triggers and the output follows the instructions.
2. 2Send a near-miss, adjacent in topic but outside the scope. Confirm the skill stays quiet.
3. 3Send a request that mentions the general topic but not the specific job. Confirm nothing fires unless it genuinely should.
4. 4If any of the three go wrong, rewrite the description first. Only touch the instructions once triggering is reliable.

Once one skill works cleanly, the next one is mostly repeating this same shape on a different repeated task, not inventing a new process. For the agent loop a skill often gets called from, see Build your first agent. For a fuller build across multiple lessons covering tools, memory, and skills together, the Building with AI course walks through the same ideas with real code.