Claude Code Skills: Turn the Prompts You Keep Retyping Into Commands

Everyone who uses Claude Code for long enough builds up a set of prompts they type again and again. "Review this diff for security issues, focusing on…" "Write the release notes in this format…" "Before you open the PR, run the linter, then the tests, then…"

Retyping them is tedious. Pasting them into CLAUDE.md makes every session carry them, even when you're doing something unrelated. Skills are the answer in between: reusable instructions that load only when they're used.

Details reflect Claude Code as of September 2026. See the skills documentation for every option.

What a skill is

A skill is a folder with a SKILL.md file in it:

.claude/skills/
└── release-notes/
    └── SKILL.md

Project skills live in .claude/skills/ and are shared with everyone who clones the repo. Personal skills live in ~/.claude/skills/ and follow you across projects.

A skill can be used in two ways:

You run it by name: /release-notes.
Claude runs it on its own, when your request matches the skill's description.

The key property is how it loads. Claude always sees each skill's short description, so it knows the skill exists. The full instructions load only when the skill is invoked. A long, detailed skill costs almost nothing until you use it.

Skills vs CLAUDE.md

This is the distinction that matters:

CLAUDE.md is for facts that are true in every session: how to run the tests, where things live, what never to do. It's loaded at the start of every conversation. Keep it short — Anthropic suggests under 200 lines. (See How to Write a CLAUDE.md That Actually Helps.)
Skills are for procedures you need sometimes: reviewing a PR, writing a migration, preparing a release. They load on demand.

If your CLAUDE.md has a long section titled "When reviewing pull requests…", that section wants to be a skill.

Writing one

A minimal skill is a header and some instructions:

---
name: release-notes
description: Writes release notes from commits since the last tag. Use when preparing a release or asked for a changelog.
disable-model-invocation: true
---

Write release notes for the changes since the last git tag.

Group them under: New, Improved, Fixed. One line per change, written for users,
not developers — describe the effect, not the implementation. Skip refactors,
dependency bumps, and test-only changes. End with a one-sentence summary.

Two header fields do most of the work:

description — how Claude decides when a skill is relevant. Say what it does and when to use it.
disable-model-invocation: true — only you can run it. Use this for anything with side effects, like a deploy or a release. You don't want Claude deciding on its own that now is a good time.

Arguments

Skills take arguments. $ARGUMENTS is everything you typed after the name, and you can name positional arguments:

---
name: fix-issue
description: Fixes a GitHub issue by number
arguments: [issue]
disable-model-invocation: true
---

Read GitHub issue #$issue with `gh issue view $issue`. Reproduce the problem,
write a failing test, fix it, and confirm the test passes. Open a draft PR
that references the issue. Do not merge.

Run it as /fix-issue 482.

Live context: running commands before Claude reads the skill

This is the feature that turns a skill from a saved prompt into something more useful. A line of the form !`command` runs the command when the skill is invoked and puts its output into the instructions:

---
name: summarize-changes
description: Summarizes uncommitted changes and flags risks. Use when asked what changed or for a commit message.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks:
missing error handling, hardcoded values, tests that need updating.
If the diff is empty, say there are no uncommitted changes.

Claude starts with the diff already in hand, instead of spending a turn going to get it. It's faster, and it's deterministic — the skill always looks at the same thing.

Pre-approving tools

A skill can grant permission for the tools it needs, for that turn:

allowed-tools: Bash(gh *) Bash(git log *) Read Grep

So a /fix-issue skill can run gh without prompting you every time, while the rest of your session keeps its normal permission rules.

Supporting files

Because a skill is a folder, it can carry more than one file: a style guide, templates, example outputs, a script. Keep SKILL.md itself focused — Anthropic suggests under 500 lines — and point to the supporting files from it. Claude reads them only if it needs them.

.claude/skills/api-endpoint/
├── SKILL.md
├── template.ts
└── conventions.md

Running a skill in its own context

Some skills do noisy work — reading a whole module, running a long check. Adding context: fork runs the skill in a subagent: it gets a fresh context window, does the work, and returns a summary to your main conversation. It's the same trade-off as any subagent — clean main context, but no access to what you've discussed. Claude Code Subagents covers when that's worth it.

Four skills worth having

1. A pre-PR check. Lint, type-check, run the tests, review the diff against your checklist, then open the PR. disable-model-invocation: true, and allowed-tools for exactly the commands it needs.

2. A focused review. Your team's review checklist — security, error handling, migrations, accessibility — as a skill Claude runs over the current diff with !`git diff main...HEAD`. Consistent reviews, every time.

3. A "how we do X" guide. How this codebase adds an API endpoint, a database table, or a background job, with a template file. Let Claude invoke it automatically when you ask for one.

4. A session handoff. Update NOTES.md with what's done, what's next, and what was ruled out; commit it. Run it before you stop for the day, and tomorrow's session starts from a file rather than a memory. (Why that matters: How to Resume a Claude Code Session.)

If you already have custom commands

Older Claude Code setups used Markdown files in .claude/commands/. Those still work — .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy. Skills are the better home for new work because they support supporting files, live context, and automatic invocation.

The rule of thumb

Typed it twice? Make it a skill.
True in every session? It goes in CLAUDE.md.
Must happen every time, no exceptions? That's a hook, not a skill — skills are instructions Claude follows, hooks are commands Claude Code runs.

Commit project skills to the repo. They're documentation of how your team works that happens to be executable — and they're just as useful to the next human who joins as to the agent.

EasySpawn runs Claude Code in a persistent workspace where your skills, hooks, and project configuration are always in place — from the browser, your phone, or SSH. See how it works or join the waitlist.