A8gent
Writing Your First Skill cover
Claude Skills Foundations · Lesson 2 of 15

Writing Your First Skill

A step-by-step method for turning a repeated task into a clean, reusable Claude Skill that gets applied consistently, built from a real release-notes example.

Start from a real repeated task

The best first Skill comes from work you already do often and want done the same way every time. Do not invent a task to practice on. Pick something concrete where you can point to good and bad examples from real history: drafting release notes, writing pull request descriptions, triaging inbound messages. We will build a release-notes Skill here because it is a task most teams do badly and inconsistently, which makes it perfect Skill material. The whole build takes about ten minutes.

Step 1: Decide where it lives, then create the folder

Skills live in one of two places, and the choice matters:

Location Scope Use when
~/.claude/skills/Personal, all your projectsYour own habits and preferences
.claude/skills/ in the repoProject, shared via gitTeam conventions everyone should get
Inside a pluginDistributed across teamsPackaging Skills for many repos or clients

Release notes are a team convention, so make it a project Skill and commit it:

mkdir -p .claude/skills/release-notes

Step 2: Write the SKILL.md

Create .claude/skills/release-notes/SKILL.md. Notice the five parts baked into it: a name and trigger, a procedure, hard constraints, a pointer to examples, and an escalation rule.

---
name: release-notes
description: >
  Generates customer-facing release notes from recent git history.
  Use when the user asks for release notes, a changelog entry,
  or "what shipped" summaries.
---

# Release Notes Generator

## Gather changes
Run: git log --oneline --no-merges v-latest..HEAD
If no tags exist, use the last 20 commits.

## Writing rules
- Group into: New, Improved, Fixed
- Write for customers, not engineers: no file names, no
  internal ticket IDs, no "refactor" entries
- One line per change, verb first ("Added CSV export to reports")
- Skip pure chores (dependency bumps, CI changes) entirely
- Match the tone of examples/sample-notes.md

## Output
Write to RELEASE_NOTES_DRAFT.md and show the user a summary.
Never publish or tag anything. If the git history is empty or
ambiguous, say so and ask, do not invent entries.

Two things to copy from this structure. First, the imperative voice: "run", "group", "never publish". You are writing operating procedure for an agent, not a wiki page for a human. Second, every constraint is detectable: a reviewer could look at output and say yes or no. "Try to keep it brief" is not a rule; "one line per change, verb first" is.

Step 3: Add a supporting example file

Create examples/sample-notes.md inside the Skill folder with two or three of your best past release notes. This is cheaper and more reliable than describing tone in prose, because Claude imitates examples extremely well, and the file costs zero tokens until Claude opens it. Your folder now looks like:

.claude/skills/release-notes/
├── SKILL.md
└── examples/
    └── sample-notes.md

Step 4: Test both invocation paths

Claude Code watches Skill directories, so the Skill is live without a restart. Test the explicit path first:

/release-notes

That slash command is the Skill's directory name (release-notes here), which is also the frontmatter name because the two match. If you set a different name, Claude Code shows and uses that as the command, and the directory name still invokes the Skill too. Invoking it explicitly guarantees activation and lets you debug the body in isolation. Then test automatic discovery by asking naturally: "write release notes for what we shipped this sprint." If Claude does not pick the Skill up, your description is the problem, not the body, because the body is invisible at decision time. Add the trigger phrases users actually say and try again.

Step 5: Iterate on failure modes

Run the Skill on three to five real releases, including at least one awkward one (a release with only chores, a repo with no tags). Every time the output is wrong, classify the failure: is this a missing rule, a vague rule, or a missing example? Add the fix to the Skill file, not to your chat message. This is the core discipline of Skill authoring: corrections go into the artifact, so you never make the same correction twice. Teams that adopt this habit end up with Skills that encode months of accumulated judgment.

How to spot a good candidate task

If you are unsure what to build first, score your repeated tasks against three criteria. Frequency: the task comes up at least weekly, so the Skill pays for itself fast and you get enough runs to iterate on. Correction history: you have caught yourself typing the same correction into chat more than twice; that correction is the seed of your first constraint. Checkable output: you can look at a result and say pass or fail without a meeting. Release notes score well on all three. "Make our strategy docs better" scores zero on the third and will produce a mushy Skill you cannot debug. Save the fuzzy tasks for later, once you have the authoring reflexes.

Keep it lean

A Skill is not a knowledge dump. Include only what changes Claude's behavior on this task; if a sentence would not alter the output, cut it. If the SKILL.md grows past roughly 400 lines, split scenario-specific content into reference files under the Skill folder and point to them from the body, keeping the always-relevant core small. That is Tier 3 progressive disclosure doing its job.

Step 6: Commit it, and review it like code

A project Skill that lives only on your laptop is a personal Skill with extra steps. Commit it:

git add .claude/skills/release-notes
git commit -m "Add release-notes skill: customer-facing changelog from git history"

Then treat it as reviewable. A SKILL.md diff is unusually easy to review well, because every line is either a rule or it is noise, and a reviewer only has to ask two questions of each one: is this checkable? and would removing it change the output? Anything failing both is prose that has wandered in.

Reviewing Skills also catches the drift that kills them. Six months in, the release-notes Skill says to read examples/sample-notes.md and that file now contains notes in a format the team abandoned. Nothing errors. The Skill just quietly produces last year's house style. Putting Skill files in the same review path as the code means the person who changes the format changes the example in the same pull request.

A worked iteration loop, verbatim

Step 5 says corrections go into the artefact. Here is what that actually looks like across three runs of the release-notes Skill, because the abstraction is easy to agree with and hard to do.

Run 1. The draft includes a line reading "Bumped axios to 1.7.4". The Skill already says to skip pure chores, so this is not a missing rule - it is a vague one. Claude did not classify a dependency bump as a chore. The fix names the category instead of gesturing at it:

- Skip pure chores (dependency bumps, CI changes) entirely
+ Skip these entirely: dependency bumps, lockfile changes, CI and
+ workflow config, formatting-only commits, test-only commits,
+ and anything whose customer-visible effect you cannot state in
+ one sentence. When unsure, omit it and list it under a
+ "Not included" heading at the bottom so a human can decide.

The second half of that edit is the part worth stealing. A rule that only says "skip" throws information away silently. A rule that says "skip, but tell me what you skipped" makes the Skill's judgment auditable, which is how you find the next vague rule.

Run 2. The output is accurate but reads like a commit log: "Added CSV export to reports", "Added PDF export to reports", "Added XLSX export to reports". Three lines for one customer-visible change. This is a missing rule:

+ - Merge commits that deliver one customer-visible capability into
+   a single line, even when they span several commits or several
+   sprints. The unit is what a customer noticed, not what was pushed.

Run 3. The tone is off - stiff, faintly corporate, nothing like the examples. This is neither a missing nor a vague rule. It is a missing example. The examples file has three entries and all three are feature announcements, so there is no model for how the team writes a bugfix line. Adding two real bugfix entries to examples/sample-notes.md fixes it, and note that this fix costs zero tokens until Claude opens the file.

Three runs, three different diagnoses, three different kinds of fix. That triage - vague rule, missing rule, missing example - is the whole skill of Skill authoring, and you get fluent at it within a dozen runs.

Turning soft rules into checkable ones

Since almost every early failure traces back to a rule nobody could check, it is worth drilling the rewrite directly.

Soft, unenforceable Checkable rewrite
Keep it conciseOne line per change, maximum 15 words, verb first
Write for a non-technical audienceNo file paths, no class or function names, no ticket IDs, no internal service names
Be careful with unclear historyIf a commit message does not state a customer-visible effect, list it under "Needs input" and do not guess
Use our toneMatch examples/sample-notes.md; if a phrasing does not appear there, do not invent one
Do not do anything riskyWrite only to RELEASE_NOTES_DRAFT.md. Never run git tag, git push, or any publish command

The test for the right-hand column: hand the output and the rule to someone who was not in the room, and they can mark it pass or fail without asking you a question. If they need to ask, the rule is still soft.

Build a fixture folder so testing is not guesswork

Testing a Skill by waiting for the next real release is slow and you will stop doing it. Keep the awkward cases as fixtures instead:

.claude/skills/release-notes/
├── SKILL.md
├── examples/
│   └── sample-notes.md
└── test-cases/
    ├── 01-normal-release.txt      # 20 mixed commits
    ├── 02-chores-only.txt         # should produce "nothing customer-facing"
    ├── 03-no-tags.txt             # exercises the fallback path
    └── 04-ambiguous-messages.txt  # should ask, not invent

Each file is real git log output you have saved. After any edit to the Skill, run all four and read the results. It takes a couple of minutes and it catches the classic regression where fixing case 4 quietly breaks case 2. Case 4 is the important one: a Skill that invents plausible release notes from unreadable commit messages is worse than one that produces nothing, because the failure is invisible until a customer reads it.

When one Skill should become two

Three signals, any one of which is enough:

  1. The description needs "or". "Use when the user asks for release notes or wants a summary of open incidents" is two Skills wearing one coat, and each one dilutes the other's routing.
  2. Half the constraints are irrelevant on any given run. If the internal-notes rules never apply when writing customer notes, they are paying activation cost for nothing.
  3. Two people own the two halves. Ownership boundaries are usually the real boundaries. Splitting along them means edits stop colliding.

Splitting is cheap - a new folder, a new SKILL.md, and both descriptions edited to say what they are not for. Leaving it unsplit gets more expensive every week.

The finished artefact, in full

Everything above is fragments and diffs. Here is the complete Skill after the three iterations, so you have one whole correct example to copy rather than assembling it yourself. This is the file, top to bottom, with nothing elided.

--- .claude/skills/release-notes/SKILL.md ---
---
name: release-notes
description: >
  Drafts customer-facing release notes from git history in our
  house format. Use when the user asks for release notes, a
  changelog, notes for a version or tag, or a summary of what
  shipped this sprint or this week. Not for internal engineering
  summaries - use eng-summary for those.
---

# Release Notes

## Procedure
1. Determine the range. Run git describe --tags --abbrev=0 for
   the latest tag, then git log --oneline --no-merges <tag>..HEAD.
   If there are no tags, use the last 20 commits and say so in
   the output. If the user named a range, use theirs instead.
2. Classify every commit into New, Improved, Fixed, or Excluded.
3. Write one line per customer-visible change.
4. Write the draft to RELEASE_NOTES_DRAFT.md.
5. Show the user the draft plus the "Not included" list.

## Writing rules
- One line per change, maximum 15 words, verb first, past tense.
  "Added CSV export to reports" - not "CSV export was added".
- No file paths, no class or function names, no ticket IDs, no
  internal service names, no commit SHAs.
- Merge commits that deliver one customer-visible capability into
  a single line, even when they span several commits or sprints.
  The unit is what a customer noticed, not what was pushed.
- If a change alters behaviour people depend on, prefix the line
  with **Breaking:**. Never omit this, even for small changes.
- Match the tone of examples/sample-notes.md. If a phrasing does
  not appear there, do not invent one.

## Exclusions
Exclude entirely: dependency bumps, lockfile changes, CI and
workflow config, formatting-only commits, test-only commits, and
anything whose customer-visible effect you cannot state in one
sentence. List every excluded commit under a "Not included"
heading at the end so a human can overrule you.

## When to stop and ask
- Commit messages do not state a customer-visible effect: list
  them under "Needs input". Do not guess what they did.
- The range is empty or the repo has no commits: say so. Do not
  produce an empty document with headings.

## Output
Write only to RELEASE_NOTES_DRAFT.md. Never run git tag, git push,
git commit, or any publish command. No preamble, no closing
summary, no offer to make further changes.

And the supporting file that carries the tone, which the body only points at:

--- .claude/skills/release-notes/examples/sample-notes.md ---
# v2.4.0

## New
- Added CSV and PDF export to every report
- Added a weekly email digest, off by default

## Improved
- Made the dashboard load in about half the time on large accounts
- **Breaking:** Renamed the "Owner" column to "Account manager"
  in all exports. Update any saved templates that reference it.

## Fixed
- Fixed invoices showing the wrong currency for UK accounts
- Fixed the date filter ignoring the last day of the range

Read the two together and notice how little the body says about tone. It says "match the examples" and then gets out of the way. The two bugfix lines in the examples file do more to set voice than a paragraph of adjectives would, and they cost nothing until Claude opens the file. This is the single highest-leverage habit in Skill authoring: show tone, state rules. Prose describing tone is the most common form of dead weight in a SKILL.md.

Reviewing a Skill: a bad one, marked up

You will review other people's Skills more often than you write your own. Two questions per line, from earlier: is this checkable? and would removing it change the output? Here is a real-shaped submission with the review comments attached.

---
name: pr-description                                  # ok
description: Helps write PR descriptions.             # (1)
---

# PR Description Skill

This skill exists because our PR descriptions have historically
been inconsistent, which makes review slower and makes it hard
for people joining the team to understand what changed. Good PR
descriptions are an important part of engineering culture.       # (2)

## Instructions
- Try to summarise the change clearly                            # (3)
- Include context about why the change was made
- Mention any testing you did                                    # (4)
- Be professional but not too formal                             # (5)
- Link the ticket if there is one
  1. The description does not route. It says what the Skill is, never when to fire. It needs the literal phrases: "Use when the user asks to write, draft, or improve a pull request description, PR body, or merge request summary." As it stands this Skill will only ever work by explicit invocation.
  2. Four lines of rationale. True, well written, and it changes no output. It costs tokens on every activation. Delete it, or move it to a README beside the SKILL.md that Claude never loads.
  3. "Try to summarise clearly" fails both tests. Not checkable, and removing it changes nothing because summarising is what the model does by default. Replace with structure: "Open with one sentence stating what changed and why, in that order, under 25 words."
  4. Ambiguous subject. "Mention any testing you did" - who is "you"? The Skill is instructing the agent, but this sentence reads as advice to the human author. Rewrite as an instruction to the agent, and make it detectable: "Include a Testing section listing the commands actually run, taken from the session, or the words 'Not tested' if none were."
  5. Unenforceable tone rule. Replace with an example file, exactly as the release-notes Skill does.

The reviewed version is about a third the length and does considerably more. That ratio is typical: first drafts of Skills are usually two-thirds prose that a reviewer can delete without losing anything.

What breaks in month three

Skills fail quietly, which is what makes maintenance a real topic rather than a footnote. Every failure below produces no error at all - the Skill runs, the output looks fine, and it is wrong.

Failure How you notice Prevention
The examples file shows a format the team abandonedOutput looks slightly dated and nobody can say whyKeep examples in the same review path as the code, so the person changing the format updates the example in the same pull request
The procedure references a command that changedThe Skill silently falls back to its "if that fails" branch every runRun the fixture cases after any tooling change; case failures surface it in two minutes
Rules accumulate and nobody removes anyActivation cost creeps up; later rules start losing to earlier onesOn every edit, ask which existing rule this one supersedes, and delete that one
A second Skill grows into the same territoryThe wrong one fires on about a third of requestsWhenever you add a Skill, re-read its neighbours' descriptions and add mutual exclusions
The Skill's author leavesNobody edits it again; it drifts until someone deletes it in frustrationName an owner in the repo's CODEOWNERS for .claude/skills/, same as any other code
Fixtures were never savedEvery edit is tested by vibes, so regressions shipSave the awkward input the day you hit it, while you still have it

The third row is the one that catches experienced people. A SKILL.md only ever grows, because adding a rule is easy and deleting one feels risky. Six months of that and the body is a sediment of overlapping instructions, several of which contradict each other, and the outputs get less predictable rather than more. The discipline is to treat every addition as a replacement until proven otherwise.

Common mistakes

  • Writing constraints as soft suggestions instead of firm, checkable rules.
  • Skipping the test cases and assuming the Skill works because it reads well.
  • Cramming a second, unrelated task into the same Skill, which blurs its trigger and weakens both.
  • Fixing failures in chat instead of in the file, so the same failure recurs next week.

What you should be able to do now

  • Create a project Skill folder and a complete SKILL.md with trigger, procedure, constraints, examples, and escalation.
  • Choose correctly between a personal Skill and a project Skill.
  • Test a Skill via slash-command invocation and via natural-language discovery, and know which failure points at the description versus the body.
  • Run a tighten-and-retest loop where every correction lands in the artifact.

Where this goes next

This is the second and last free lesson. With what a Skill actually is behind you, you can now write one, commit it, test it against fixtures, and tighten it until it stops surprising you. Go and do that on one real task before spending money on anything - the reflexes only come from runs.

The paid lessons handle what a single Skill cannot. Supporting-file structure that keeps a large Skill cheap. Subagents: when handing work to a fresh context beats doing it inline, how to brief one so its report is usable, and how state comes back. Hooks and tool permissions, which are the actual enforcement layer - the place where "never publish" stops being a sentence and starts being a rule. Wiring MCP servers in so Skills reason over live data. And packaging a whole set as a plugin you install across repos or ship to a client. Every lesson ships the files it builds.

If you would rather the system existed than learn to build it, we do this as project work - see AI automation services, or start with the free automation audit, which is a straight read on which of your repeated tasks is worth encoding first and which is not worth touching. For the surrounding concepts, the agentic workflow and human in the loop entries are short and practical.

Drop your email in the box below and the two free lessons arrive with the actual SKILL.md files, the examples folder, and the test-case fixtures - which is a faster start than retyping any of it.

Key takeaways

What to remember from this lesson

  • Build your first Skill from a task you already repeat, not an invented practice task - you need real good and bad examples to iterate against.
  • Score candidate tasks on three criteria: weekly frequency, a correction you have typed more than twice, and output you can call pass or fail without a meeting.
  • Write in imperative voice and make every constraint detectable. 'One line per change, verb first' is a rule; 'try to keep it brief' is not.
  • The slash command is the frontmatter name when you set one, otherwise the directory name, and the directory name always invokes it too. Test explicit invocation first, then natural discovery.
  • Corrections go into the artifact, never into the chat message. That is what makes a Skill compound instead of evaporate.

Try it yourself

Score your candidate tasks and pick the first Skill

Everyone picks their first Skill by which task feels most impressive, and everyone picks wrong. Implement the three-criteria score from the lesson so the candidates rank themselves. The candidate list in the check is a fixture.

Write it

Write the description that decides whether your Skill loads

The description is the routing decision, so it has to say what the Skill does AND name the literal situations that should trigger it. The rules below check structure only - whether the phrases a real user would type are present. They cannot judge whether your wording is good, so read your draft back against the ten inputs from the lesson afterwards.

2 of 6 checks passing

  • Says what the Skill produces, not just its topic
  • Names the trigger situation explicitly
  • Quotes the literal phrases a user would actually type
  • Avoids vague filler that describes no situation
  • Long enough to distinguish it from a neighbouring Skill
  • Short enough to stay cheap at discovery

These checks look at structure only, not quality. A prompt can pass every one and still be a poor prompt, so read it back and ask whether you would understand it cold.

Exercise

Ship a working release-notes Skill and break it on purpose

30 min
  1. 1Pick one repeated task and score it out of 3 on frequency, correction history, and checkable output. If it scores under 2, pick a different one.
  2. 2Run `mkdir -p .claude/skills/<your-task>` inside a real repo and create SKILL.md with the five parts from the lesson: frontmatter trigger, procedure, hard constraints, a pointer to examples, and an escalation rule.
  3. 3Add examples/ with two or three of your best past outputs for this task, pasted verbatim from real history.
  4. 4Invoke it explicitly with /<your-task>. Then, in a fresh session, ask for the same thing in plain language without naming the Skill.
  5. 5Run it on three real inputs, including one awkward case (empty history, missing data, an ambiguous request).
  6. 6For each wrong output, classify the failure as missing rule, vague rule, or missing example, and fix it in SKILL.md - not in chat. Re-run the same three inputs.

You are done when Both invocation paths work - the slash command and a plain-language request that never names the Skill - and your three real inputs including the awkward one all produce output you would ship, after at least one fix that landed in the file rather than in a chat message.

Companion files

The release-notes Skill, ready to commit

The finished folder from this lesson - SKILL.md plus examples/sample-notes.md - so you can compare your version against a complete one that has all five parts.

The free-preview pack includes 4 files of runnable code and config for Writing Your First Skill, plus the other free lessons of this course. No email needed.

Free preview pack - 9 KB zip

Check yourself

Answer before you reveal

Your Skill's directory is `release-notes` but its frontmatter name is `changelog-writer`. What is the slash command?Show answer

/changelog-writer is the command the / menu shows, because a frontmatter name sets the command when you give one. /release-notes, the directory name, still invokes it as well. Keep the two identical to avoid the confusion.

A teammate proposes 'make our strategy docs better' as a first Skill. Why is that a bad choice?Show answer

It fails the checkable-output test - you cannot say pass or fail without a meeting, so you can never tell whether an edit to the Skill helped. Save fuzzy tasks until you have the authoring reflexes.

Your SKILL.md has grown past 400 lines. What do you do?Show answer

Split the scenario-specific content into reference files inside the Skill folder and point at them from the body, keeping the always-relevant core small. Tier 3 means those files cost nothing until Claude opens them.

Free lesson notes

Get the notes pack for Claude Skills and Subagents Course for Builders, plus every new module free by email.

No card, no spam, unsubscribe any time.