Write your first agent skill, step by step

The best first skill is one that captures something you already do well and are tired of explaining. In this chapter you’ll build a complete, working skill from an empty folder: a pull-request description writer that turns a branch’s changes into a clear, consistent description. Along the way you’ll learn the pieces every skill needs. You can follow the same steps for any task, from meeting notes to SEO briefs.

Step 1: choose the job

Good first skills share three traits: the task comes up often, you can tell a good result from a bad one, and the agent gets it slightly wrong without help. Before writing anything, jot down how you’d do the task and what you usually correct.

• Task: write a pull-request description for the current branch.
• What good looks like: a one-line summary, why the change was made, what changed, how it was tested, anything risky.
• What the agent gets wrong without help: lists every file instead of explaining the change, invents testing it didn’t do, forgets the risks.

Step 2: create the folder

A skill is a folder whose name matches the skill’s name. Use lowercase letters, numbers and hyphens. For a personal skill in Claude Code, create it under ~/.claude/skills/; for a team skill, under .claude/skills/ in the repository.

Step 3: write the frontmatter

The frontmatter is a YAML block at the very top of SKILL.md, between two lines of three dashes. It needs two fields. name identifies the skill. description tells the agent what the skill does and when to use it; this is what the agent reads to decide whether to load the skill, so be specific.

Step 4: write the instructions

After the frontmatter comes the body, in plain Markdown. Write it like a briefing for a capable colleague who has never seen your project: clear steps in order, the rules that matter, and what to do in awkward cases. Prefer specific instructions (“run git log main..HEAD --oneline”) over general ones (“look at the changes”).

Step 5: add an example

One good example teaches tone and level of detail better than a page of rules. Add it at the end of the body, clearly labelled as an example so the agent doesn’t copy it word for word.

The complete file

Put the three parts together, frontmatter, body and example, and you have a finished skill. It’s a single file, short enough to read in two minutes, and it covers what the agent needs every time. There are no scripts or extra files yet; Chapter 10 shows when to add them.

Step 6: try it

1. Start a new session in a repository with a branch that has a few commits.
2. Ask in your own words: “Can you write the PR description for this branch?”
3. Watch for the skill being loaded, then check the result against your format.
4. Try a second phrasing, such as “I’m about to open a pull request, draft the text”, to check the description triggers reliably.
5. Try an awkward case: a branch with no clear reason for the change. Does the agent ask, as instructed?

Step 7: refine

Your first version won’t be perfect, and that’s fine. Each time the agent does something you’d correct, decide whether it’s a missing rule, an unclear step or a weak example, and fix that one thing. Keep the file focused. When it starts growing past what every use needs, move detail into separate files. Chapter 11 covers testing and iteration properly.

Common first-skill mistakes

• Writing a description that says what the skill is but not when to use it.
• Restating generic advice the model already follows, which costs context and adds nothing.
• Making one skill do several unrelated jobs. Split it.
• Using vague verbs such as “handle”, “manage” or “deal with” instead of concrete actions.
• Forgetting to tell the agent what not to do, such as claiming tests it didn’t run.

Skill CreatorAgent skillAsk an agent to interview you and draft a skill with this.Agent skill · MITWriting Skills GuideAgent skillA methodical, test-first approach to writing skills.Agent skill · MITRRepository onboarding skillPromptA ready-made example skill to study and adapt.In a pack

Key takeaways

• A skill is a folder named after the skill, containing SKILL.md.
• Frontmatter needs name and a specific description covering what and when.
• The body is a clear briefing: steps, format, rules and one example.
• Test with several phrasings and an awkward case, then refine one thing at a time.