Writing your first skill
A skill is a markdown file with two required fields and a body. The whole format is deliberately small.
The minimum
--- name: changelog-writer description: Writes changelog entries from git history. Use when preparing a release or when the user asks for a changelog. --- # Changelog Writer ## Steps 1. Run `git log --oneline` since the last tag to see what changed. 2. Group commits into Added, Changed, Fixed, and Removed. 3. Write one line per user visible change, in plain language. ## Rules Describe the effect on the user, not the implementation. "Fixed a crash when uploading files over 10 MB" beats "patched null check in upload handler". Skip internal refactors that no user can observe.
That is a complete, working skill.
The description field is the whole game
name and description are the only parts loaded up front. Everything else is read only after the agent decides the skill is relevant.
That decision is made entirely from the description. Which means a brilliant skill with a vague description never runs.
Write it as a trigger, not a summary:
- Weak: "Helps with changelogs."
- Strong: "Writes changelog entries from git history. Use when preparing a release or when the user asks for a changelog."
The phrase "use when" is doing the work. It tells the model the situation, not just the topic.
Write steps, not philosophy
The body is read when the agent has already decided to act. It wants procedure.
Number the steps. Put the command to run inside the step. Say what "done" looks like. Save the reasoning for a short rules section at the end, and only where the reasoning changes behaviour.
Keep one skill to one job
A skill called code-helper that reviews, tests, and documents will trigger constantly and do the wrong one. Three skills with three sharp descriptions each fire when they should.
If you cannot write a one sentence description without using "and", it is probably two skills.
Test the trigger before the content
Put the skill in place, start a fresh session, and describe your situation in your own words without naming the skill. If it does not load, the description is wrong. Fix that before polishing anything in the body.
This is the step people skip, and it is the one that determines whether the skill is ever used.
Where files live
Project skills usually sit in .claude/skills/<name>/SKILL.md for Claude Code, with equivalent paths in other harnesses. Personal skills go in your home directory equivalent so they follow you across projects.
Check your harness documentation for the exact path, because this is one of the places harnesses genuinely differ.
Next
Browse the skills directory for working examples, then read subagents and delegation for when a skill should become a separate agent instead.