Creating reusable Claude Code skills

If I type the same instructions three times, I turn them into a skill.

A skill can be a short saved prompt. You can invoke it with a command such as /review, or let Claude load it when the description matches your request. If the workflow grows, the same skill can include templates, examples, scripts, and references.

Claude Code still supports files in .claude/commands/. Existing commands do not need an urgent migration. For anything new, I would use .claude/skills/<name>/SKILL.md because it gives you more room without making the first version complicated.

Create one small skill

Start with a project review:

my-website/
  .claude/
    skills/
      review/
        SKILL.md
  index.html

Put this in SKILL.md:

---
name: review
description: Review the current project and list visible problems.
disable-model-invocation: true
---

Review the current state of the project.
Check for placeholder content, broken links, inconsistent styling, and unfinished work.
Give me a short list of what needs attention.

The folder name becomes the command. Type /review and Claude loads those instructions. Run /skills to see everything currently available.

You do not need to restart anything. Claude Code watches these folders, so an edit to SKILL.md takes effect in the session you are already in. That makes the first few versions cheap to get wrong.

I set disable-model-invocation: true for a review I want to start myself. Remove that line when you want Claude to use the skill automatically after recognizing a matching request.

Pass an argument

Use $ARGUMENTS when the same workflow should accept a different file or topic each time.

Create .claude/skills/explain/SKILL.md:

---
name: explain
description: Explain a file or part of the project in plain English.
disable-model-invocation: true
argument-hint: "[file or topic]"
---

Explain what $ARGUMENTS does in plain English.
Assume I am not a programmer. Focus on what it does and what depends on it.

Now type:

/explain index.html

Claude receives index.html in place of $ARGUMENTS. The same skill can explain a stylesheet, navigation section, or build script.

Three useful starters

I would begin with one of these:

• /review: inspect the current changes and list visible or functional problems
• /explain [file]: explain what a file does and what could break if it changes
• /check-mobile: inspect the HTML and CSS for likely mobile problems, then test below 640px when a browser integration is available

That last boundary matters. A prompt cannot prove how a page renders by reading code alone. If Claude cannot open a browser, the skill should tell you what to check yourself.

For a writing project, a /proofread [file] skill can check spelling and awkward phrases. For file organization, /duplicates can find matching names and sizes, but it should report first and wait before deleting anything.

Save the checks and safety rules you do not want to remember each time. The short command is only the trigger.

Project or personal

Keep repository-specific skills inside the project:

.claude/skills/review/SKILL.md

Put it in your home configuration when it applies across projects:

~/.claude/skills/review/SKILL.md

Most of my website workflows now live as project skills. I keep review, bug fixing, and blog work separate because each needs different instructions and safety checks.

Skills follow the Agent Skills open standard rather than a Claude-only format, so a skill you write is not locked to one tool, and you can package a set of them as a plugin if you want to share them. Neither matters for your first one. Both matter once you have five you would rather not rewrite.

Do not begin by building a large library. Use the three-use rule. When you have typed the same detailed instruction for the third time, save it. If the workflow later needs a template or validation script, add it to the skill directory then.

Skills and CLAUDE.md do different jobs

CLAUDE.md holds concise project facts and instructions that should be available in each session. A skill holds a reusable action that loads when you or Claude invokes it.

Put “use pnpm for this project” in CLAUDE.md. Put the steps for reviewing a release in a skill.

Anthropic's current skills documentation covers supporting files, argument options, invocation controls, and the legacy command format.

Start with one repeated prompt. Save the decisions and checks, not just the sentence you are tired of typing.