How to Write a Claude Code Skill: A Build-Your-Own SKILL.md Guide

A Claude Code Skill is one of the simpler things to build and one of the easier things to build badly. The mechanics take five minutes — a folder, a file, two frontmatter fields. The part that decides whether the skill is useful is the writing: a description sharp enough to trigger at the right moment, and instructions tight enough not to waste context.

This is a build-your-own walkthrough. You’ll create a SKILL.md, write a description that actually fires, structure the instructions, add optional supporting files, keep the whole thing lean, test it, and share it. If you haven’t met the format yet, read Claude Code Skills explained first — this guide assumes you know what a skill is.

By the end you’ll have a working skill and a feel for the two failure modes: skills that never trigger, and skills that trigger but bloat every conversation.

Step 1: Create the folder and file#

A skill is a directory with a SKILL.md inside. The folder name is the skill’s identity, so name it for what it does:

mkdir -p .claude/skills/changelog-entry

On Windows in PowerShell:

New-Item -ItemType Directory -Force -Path .claude\skills\changelog-entry

Use .claude/skills/ in the repo for team skills, or ~/.claude/skills/ for personal ones — on Windows that’s C:\Users\YourName\.claude\skills\. Now create SKILL.md inside that folder.

Step 2: Write the frontmatter#

Two fields do the work:

---
name: changelog-entry
description: Use when adding an entry to CHANGELOG.md after a merged change. Follows Keep a Changelog format and groups entries under Added, Changed, Fixed, or Removed.
---

That’s a valid skill header. The name keeps it identifiable; the description is the part you’ll come back and tune.

Step 3: Write a description that triggers#

This is the step that makes or breaks the skill. Claude reads the description — not the body — to decide whether the skill applies. So the description has to name the situation in the words you’d actually use when asking.

Compare these:

Lead with “Use when…” and finish the trigger condition. Mention the artifact (a file type, a tool, a command), the moment (after a merge, before an apply, when writing tests), and any keywords you naturally reach for. A description written as a summary — “this skill handles changelogs” — reads fine to a human and means nothing as a trigger.

Step 4: Structure the instructions#

Below the frontmatter, write what Claude should do once the skill is active. Plain Markdown, ordered for a procedure, specific to your rules:

# Changelog entry

When asked to add a changelog entry:

1. Open CHANGELOG.md and find the `## [Unreleased]` section.
2. Add the entry under the right subsection: Added, Changed, Fixed, or Removed.
3. Write it as a single line, past tense, describing user-visible impact.
4. Link the PR number at the end in parentheses.
5. Don't touch released version sections.

## Example
### Fixed
- Login no longer drops the session on transient 401s (#482)

Keep it to your rules. Don’t explain what a changelog is or how Markdown works — Claude knows. Every line you write is a line that loads when the skill fires, so the instructions should be the part only you could have written.

Step 5: Add supporting files (optional)#

When a skill needs more than instructions — a template to fill, a script to run, a reference doc — put those files in the skill folder and point to them from SKILL.md. Claude pulls them in on demand, so they don’t cost anything until used.

.claude/skills/changelog-entry/
  SKILL.md
  template.md

For the full entry format, follow template.md in this skill folder.

This is how you keep SKILL.md lean while still shipping detail. Long format specs, lookup tables, and helper scripts belong in supporting files, referenced from the main instructions rather than pasted into them.

Step 6: Keep it concise for token cost#

The whole appeal of skills is cheap-until-needed loading. You keep that benefit by writing tight. A skill that loads three screens of instructions for a one-line task is working against the design.

Practical trims:

• Cut anything Claude already knows (syntax, definitions, general advice).
• Keep only your specific rules and conventions.
• Move long references into supporting files.
• One concern per skill — don’t bundle changelog rules with commit rules.

Step 7: Test it#

Open Claude Code in the project and ask for the task the skill targets:

Add a changelog entry for the session-refresh fix in PR 482

Watch what happens. If the skill loads and follows your rules, it works. Two common failures:

• It doesn’t fire. The description is too vague or missing the words you used. Rewrite it to name the trigger, then try again.
• It fires but ignores a rule. The instructions are ambiguous or buried. Make the rule explicit and put the important ones first.

Iterate on the description and instructions until both the trigger and the behavior are reliable. This loop is most of the real work.

Step 8: Share it#

To share a skill, commit it. A skill in .claude/skills/ travels with the repo, so anyone who clones the project gets it without setup. Because the Agent Skills format is portable, the same folder also works across Claude tools that support skills — author once, reuse everywhere.

For team skills, treat the SKILL.md like any other reviewed code: open a PR, let someone read the instructions, merge it. That keeps your shared skills accurate and stops half-baked ones from spreading.

Wrapping up#

The mechanics of a skill are trivial; the value is in the writing. Spend your effort on a description that triggers and instructions that say only what’s yours to say. Build one, test it against a real task, tune the description until it fires every time, then commit it.

From here, browse the best Claude Code Skills for 2026 for ideas worth encoding, and see the Claude Code power-user guide for where skills fit alongside MCP servers, subagents, and hooks.