Write Claude Code Skills

Skills are reusable Claude Code capabilities stored as SKILL.md files.

Create a skill when you keep pasting the same checklist, workflow, rubric, or domain instructions into Claude. Unlike CLAUDE.md, the full skill body loads only when the skill is used, so detailed guidance can stay out of the main context until it matters.

Basic structure

Each skill is a folder with a required SKILL.md file.

.claude/skills/review-diff/
  SKILL.md
  examples.md
  scripts/
    validate.sh

The folder name controls the slash command:

.claude/skills/review-diff/SKILL.md -> /review-diff

First skill

---
description: Reviews the current git diff for correctness risks, missing tests, and accidental scope creep. Use when the user asks to review changes before committing.
---

Review the current changes.

## Context

```!
git diff HEAD
```

## Instructions

- Summarize the change in 2-3 bullets.
- Flag correctness risks, missing tests, and accidental scope creep.
- Ignore style preferences unless they affect maintainability.
- If there is no diff, say there are no uncommitted changes.

Invoke it directly:

/review-diff

Or ask naturally:

Review my current changes before I commit.

Where skills live

Location	Path	Scope
Personal	`~/.claude/skills/<skill-name>/SKILL.md`	All your projects
Project	`.claude/skills/<skill-name>/SKILL.md`	Current project
Nested project	`apps/web/.claude/skills/<skill-name>/SKILL.md`	Relevant subdirectory
Plugin	`<plugin>/skills/<skill-name>/SKILL.md`	Where the plugin is enabled

Use personal skills for your own workflow. Use project skills for team-specific conventions that should travel with the repository.

What belongs in a skill

Good skill content:

A repeatable task workflow.
Domain-specific rules.
Review rubrics.
Release or deploy steps.
Code generation patterns.
Links to supporting files.
Commands that collect current context.

Move long reference material into supporting files and link to it from SKILL.md.

What belongs in CLAUDE.md instead

Use CLAUDE.md for short, always-on project instructions:

The normal test command.
Code style that applies everywhere.
Repository etiquette.
Non-obvious architecture constraints.

If the instruction is long, optional, or procedural, it probably belongs in a skill.

Useful frontmatter

---
name: review-diff
description: Reviews the current git diff for correctness risks and missing tests.
when_to_use: Use before committing, opening a PR, or handing work to a reviewer.
argument-hint: "[focus-area]"
disable-model-invocation: true
allowed-tools:
  - Bash(git diff *)
  - Bash(git status *)
---

Important fields:

description: how Claude decides when the skill is relevant.
when_to_use: extra trigger guidance.
argument-hint: autocomplete hint for direct invocation.
arguments: named positional arguments available inside the skill.
disable-model-invocation: only the user can run it directly.
user-invocable: false: Claude can use it, but it is hidden from the slash menu.
allowed-tools: pre-approve specific tools while the skill runs.
disallowed-tools: temporarily remove tools while the skill is active.
context: fork: run the skill in an isolated subagent context.
agent: choose the subagent type when using context: fork.
paths: only activate the skill for matching files.

Control invocation

By default, both you and Claude can invoke a skill.

Use this for workflows with side effects:

disable-model-invocation: true

Good examples:

Deploying.
Sending Slack messages.
Publishing packages.
Merging PRs.
Running expensive automation.

Use this for background knowledge:

user-invocable: false

Good examples:

Legacy system context.
Domain glossary.
API conventions that are only useful when relevant.

Pass arguments

Use $ARGUMENTS for everything after the skill name.

---
description: Fixes a GitHub issue by number.
argument-hint: "[issue-number]"
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS.

1. Read the issue.
2. Find the relevant files.
3. Implement the fix.
4. Add or update tests.
5. Summarize the result.

Invoke it:

/fix-issue 123

For positional arguments, use $0, $1, or named arguments:

arguments:
  - component
  - from_framework
  - to_framework

Migrate $component from $from_framework to $to_framework.

Inject dynamic context

Use shell injection when the skill needs current data before Claude reasons.

## Current repo state

```!
git status --short
git diff --stat
```

This runs before Claude sees the skill content. Claude receives the rendered output, not the command placeholder.

Use dynamic context for:

Current diffs.
PR metadata.
Test output.
File lists.
Version information.

Keep commands narrow and safe. For untrusted repos, review skills before enabling workspace trust.

Add supporting files

Keep SKILL.md short and link to detailed files.

api-review/
  SKILL.md
  rubric.md
  examples.md
  scripts/
    check-openapi.js

In SKILL.md:

Use [rubric.md](rubric.md) for the full review checklist.
Use [examples.md](examples.md) for expected output format.
Run `scripts/check-openapi.js` only when reviewing OpenAPI changes.

The main file should explain what exists and when Claude should load it.

Run in a subagent

Use context: fork when the skill should run in an isolated context.

---
description: Researches a codebase topic and returns file-specific findings.
context: fork
agent: Explore
---

Good uses:

Broad investigation.
Independent review.
Security checks.
Searching many files.

Do not use context: fork for passive style rules. A forked skill needs an actual task.

Good skill design rules

Put the trigger use case first in the description.
Keep the body concise.
Move long references into supporting files.
Prefer checklists and exact steps over prose.
Make side-effecting skills user-invoked only.
Pre-approve only narrow safe tools.
Include a verification step for task skills.
Test the skill with direct invocation and natural language.

Troubleshooting

If a skill does not trigger:

Strengthen the description.
Add when_to_use with likely user phrases.
Invoke it directly once to verify the file works.
Check that it lives in a discovered skills directory.

If a skill triggers too often:

Narrow the description.
Add paths if it only applies to certain files.
Set disable-model-invocation: true if timing matters.

If the skill bloats context:

Shorten SKILL.md.
Move reference material into separate files.
Remove examples that are not needed on every run.

If the skill performs risky actions:

Remove broad allowed-tools.
Add disable-model-invocation: true.
Move irreversible actions behind explicit user approval.