Claude Code Skills: Stable Patterns, Setup, and Examples That Still Work

What We Tested and What We Did Not

We read the official Anthropic documentation and created skill files matching the documented format. We confirmed the claude binary is installed (v2.1.119). We did not start an interactive Claude Code session, so we did not verify that Claude recognizes or loads skills at runtime.

What we did:

• Created ~/.claude/skills/summarize-changes/SKILL.md matching official syntax
• Wrote YAML frontmatter and dynamic injection syntax (!`command`)
• Confirmed CLI presence

What we did not do:

• Start an interactive session to test skill invocation
• Verify auto-discovery across directories
• Test Desktop or Web behavior
• Run any bundled or community skills

Sections below note their source so you know what to verify yourself.

What Are Claude Code Skills?

A skill is a directory containing a SKILL.md file. That file has two parts: YAML frontmatter between --- markers, and markdown instructions that Claude follows when the skill runs.

Claude loads a skill in two ways:

• Automatically— when your request matches the skill's description
• Manually — when you type /skill-name in the chat

The directory name becomes the command. A skill at ~/.claude/skills/summarize-changes/ is invoked with /summarize-changes.

How Skills Differ from Related Concepts

Source: Official docs + Community

Note on network access:Skills can run shell commands and scripts, but what actually works depends on your environment permissions, API keys, network connectivity, and Claude Code's permission system. A skill that calls curl will fail if the machine has no internet. A skill that runs docker will fail if Docker is not installed. This guide does not cover Desktop or Web behavior.

Why Skills Exist

Source: Official docs

Anthropic's stated reason: "Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat."

The key difference from CLAUDE.md is loading behavior. CLAUDE.mdis always in context. A skill's body loads only when it is used, so long reference material costs nothing until you need it.

File Structure and Format

Source: Official docs + Partial test

Minimum Viable Skill

skill-name/
└── SKILL.md

We created this directory structure and matched it to the official docs. We did not start an interactive Claude Code session to confirm the skill loads.

Full Skill Directory

skill-name/
├── SKILL.md           # Required. Entry point.
├── template.md        # Optional. Template for Claude to fill.
├── examples/
│   └── sample.md      # Optional. Example output.
└── scripts/
    └── helper.py      # Optional. Executable script.

The official docs recommend referencing supporting files from SKILL.md so Claude knows what each contains and when to load it.

SKILL.md Format

---
description: Summarizes uncommitted changes and flags anything risky.
---

## Current changes

!`git diff HEAD`

## Instructions

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

The description field is recommended. Claude uses it to decide when to apply the skill automatically. If you omit it, Claude falls back to the first paragraph of the markdown body.

Where Skills Live

Source: Official docs + Partial test

Priority is Enterprise > Personal > Project. Plugin skills use a plugin-name:skill-name namespace, so they cannot conflict with other levels.

We created a skill at ~/.claude/skills/summarize-changes/ and matched the file structure to the official specification. We did not verify that Claude Code detects it across projects.

Live Change Detection

Source: Official docs

Claude Code watches skill directories for file changes. Adding, editing, or removing a skill under ~/.claude/skills/, the project .claude/skills/, or an --add-dir directory takes effect within the current session without restarting.

One exception: creating a top-level skills directory that did not exist when the session started requires restarting Claude Code so the new directory can be watched.

Stable Patterns

Source: Official docs + Community

The patterns below are organized by what they do, not by trendiness. They use core features — file structure, frontmatter, dynamic injection — that are unlikely to change.

Pattern 1: Git Workflow Automation

What it does: Summarize uncommitted changes, suggest commit messages, flag risks.

Source: Official docs

This is the official docs example. It uses dynamic context injection to pull the live diff into the prompt before Claude reads it.

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

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

The !`git diff HEAD` line is preprocessing, not something Claude executes. Claude Code runs the command and replaces the line with its output before Claude sees the skill content. The skill arrives with the current diff already inlined.

Why this pattern is stable: It uses dynamic injection and description matching — core features documented since skills launched. No experimental flags.

Pattern 2: Code Review Checklist

What it does: Enforce consistent review criteria across a team.

Source: Official docs + Not tested

Structure:

• SKILL.md with review criteria
• Optional examples/ with past review outputs
• disable-model-invocation: true so the skill only runs when explicitly called with /review

We derived this from the official frontmatter reference and community patterns referenced on Hacker News. We did not implement or test it.

Pattern 3: Project Conventions

What it does: Encode API patterns, naming conventions, or architecture rules.

Source: Official docs + Not tested

This is "reference content" in the official docs taxonomy — knowledge Claude applies to your current work, not a task to execute. Claude loads it automatically when you edit matching files.

You can limit activation with the paths: frontmatter field:

---
description: API design patterns for this codebase
paths: "src/api/**/*.ts"
---

We have not tested whether paths matching works as documented.

Pattern 4: Self-Contained Tool

What it does: Script that talks to an API or runs local commands without external dependencies.

Source: Community — not independently verified

Nick Nisi, a developer who presented on skills at his company in October 2025, described a "GPT-5 Consultant" skill: a self-contained script that knows how to talk to the OpenAI API. No external MCP server needed. "Clean. No external MCP needed."

This pattern is useful when you need a quick integration and do not want to set up and maintain an MCP server. The tradeoff: the script runs in your environment, so you manage credentials and errors.

We did not verify this skill exists or works as described.

Pattern 5: Visualization and Reporting

What it does: Generate HTML reports, dependency graphs, or codebase maps.

Source: Official docs + Not tested

The official docs include a codebase visualizer example: a Python script that scans a directory tree and generates a self-contained HTML file with collapsible directories, file sizes, and type breakdowns. The script uses only built-in libraries.

The skill references the script with ${CLAUDE_SKILL_DIR} so the path resolves correctly regardless of where the skill is installed:

Run the visualization script:

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```

We did not run this script.

What Ages Fast

Source: SERP observation + Editorial

Community Source Decay

On 2026-05-22 we checked a single Google search results page for "Claude Code skills." Of five sources in the top ten results:

This is a small SERP sample, not a systematic study. Three of five sources from one results page were unavailable during our check.

What This Means

• Stable: File structure, frontmatter syntax, core concepts. These are tied to the product and documented officially.
• Ages fast:Specific skill lists, "best of" roundups, trendy examples. These depend on community interest and hosting continuity.
• Action: Learn patterns, not specific skills. Verify any community skill in a throwaway project before relying on it.

How to Verify a Skill Still Works

1. Check the official docs for syntax changes
2. Test in a temporary project before adding to your workflow
3. Prefer bundled skills (/debug, /code-review) — Anthropic maintains these

Claude Code vs Desktop/Web

Source: Community + Not tested

This guide focuses on Claude Code CLI. We do not cover Desktop or Web behavior in detail because we have not tested it.

Nick Nisi, a developer who presented on skills at his company in October 2025, noted that skills in Claude Desktop and Web may have restrictions not present in the CLI. Specifically, he observed that network-dependent skills — those calling external APIs or running curl — may behave differently or fail in Desktop/Web environments.

We did not verify this. If you write a skill that relies on network access, test it in your target environment before sharing it.

Common Frontmatter Fields

Source: Official docs

Essential Fields

Invocation Control

Use disable-model-invocation: true for workflows with side effects — deploy, commit, send messages. Use user-invocable: false for background knowledge that is not meaningful as a direct command.

Execution Control

Dynamic Content

Important: Command output is inserted as plain text and is not re-scanned for further placeholders. A command cannot emit a placeholder for a later pass to expand.

Bundled Skills

Source: Official docs

These ship with Claude Code and are maintained by Anthropic. They are generally safer to rely on than random community lists.

Built-in Skills

Runtime Skills (Claude Code v2.1.145+)

/run and /verify infer launch commands from your project type, README, package.json, or Makefile. For non-standard setups — databases, env files, multi-step builds — use /run-skill-generator once to record the recipe.

Troubleshooting

Source: Official docs

Skill Not Triggering

• Check that description includes keywords a user would naturally say
• Verify the skill appears when you ask "What skills are available?"
• Try rephrasing your request to match the description more closely
• Invoke it directly with /skill-name to confirm it works

Skill Triggers Too Often

• Make description more specific
• Add disable-model-invocation: true if you only want manual invocation

Skill Description Cut Short

Skill descriptions share a context budget that scales at 1% of the model's context window. When the budget overflows, descriptions for skills you invoke least are dropped first.

To raise the budget, set skillListingBudgetFraction in settings (e.g., 0.02 for 2%). To free budget, set low-priority skills to "name-only" in skillOverrides so they list without a description.

What to Do Next

Start with one project-local skill. Keep it small. Test it in a throwaway repo before adding it to your main workflow.

Specifically:

1. Create a project skill at .claude/skills/my-first-skill/SKILL.md
2. Write a simple description — one sentence about what it does
3. Add basic instructions — a checklist or procedure you repeat often
4. Test it — open Claude Code in that project and type /my-first-skill
5. Iterate — adjust the description until Claude triggers it when you want

Prefer stable patterns over community roundups. The patterns in this guide use core features that are unlikely to change. Community roundups can age quickly, so verify them before relying on them.

If you need a starting point, use the bundled skills. /debug and /code-review ship with Claude Code and are maintained by Anthropic. They are generally safer to rely on than random community lists.

Resources

Official

• Claude Code Skills Docs
• Anthropic Skills GitHub

Community

• Nick Nisi — Why Everyone Should Try Claude Skills
• Simon Willison — Claude Skills