Claude Code Skill: Hands-On SKILL.md, Auto-Invoke & Teams (2026)

Tired of repeating the same instructions to Claude Code every session? Code review steps, test procedures, commit message rules — your project has established workflows, but explaining them from scratch every time is a waste. Claude Code Skills let you encode these workflows into /slash-commands that run with a single invocation. In my own setup, roughly 100 review requests per month collapse into about 5 seconds each via a single /review call. The real win isn’t the minutes saved — it’s escaping the friction of pasting the same long prompt over and over. Distribute Skills to your team via GitHub and people start customizing them, growing an ecosystem you didn’t have to maintain alone. When I show Skills to non-engineer colleagues, they invariably react with “I had no idea Claude Code had something this powerful.” My recommended workflow: let AI draft the SKILL.md and then review it yourself before shipping.

This guide covers angles that the official docs and community posts haven’t fully organized yet: when to migrate from Custom Commands, how Skills differ from CLAUDE.md, how they compare to Cursor and Devin Desktop (formerly Windsurf) rules, the February 2026 Check Point vulnerability disclosure (CVE-2025-59536) affecting Claude Code project configuration files, and the SDK-side limitation where allowed-tools can be bypassed. Everything is grounded in what I actually hit in production. For context, the official anthropics/skills repository has crossed 113,000 stars as of April 2026 — the ecosystem is expanding fast.

What Are Skills? — Claude Code’s Custom Slash Commands

Skills are Claude Code’s mechanism for packaging reusable workflows into slash commands. Instead of pasting long instructions into your prompt each time, you write a SKILL.md file once, and Claude Code makes it available as a command you can invoke with /skill-name. Think of them as functions for your AI assistant — defined once, called anywhere.

The Basics

Every Skill lives in a folder under .claude/skills/. The folder name becomes the slash command. Inside, a SKILL.md file contains frontmatter (metadata) and instructions (the actual prompt). Here’s the simplest possible Skill:

.claude/
└── skills/
    └── review/
        └── SKILL.md

When you type /review in Claude Code, it reads the SKILL.md, loads the instructions into the conversation context, and follows them. The power comes from progressive disclosure: at startup, Claude only reads the frontmatter of each Skill (roughly 100 tokens). The full instructions are loaded only when the Skill is actually invoked or when Claude determines it’s relevant to the current task. This means you can register dozens of Skills without bloating your context window.

The Kitchen Analogy — MCP Is the Kitchen, Skills Are the Recipes

The cleanest mental model comes from Anthropic’s official guide: MCP (Model Context Protocol) is the kitchen — it provides the knives, pots, and ingredients (tools and data sources). Skills are the recipes — the step-by-step instructions that tell Claude how to use those tools. A fully stocked kitchen doesn’t cook dinner; a recipe does. MCP defines what Claude can do; Skills define how Claude should do it.

Progressive Disclosure — The Three-Stage Loading Model

Skills are built on progressive disclosure: instead of loading every Skill’s full content up front, Claude loads just enough to decide whether a Skill is relevant, and the rest only when needed. This happens in three stages:

A note on the numbers: the “~100 tokens per Skill” figure isn’t stated verbatim in the official docs — it’s an empirical estimate based on typical description length. The official guarantee is that in a normal session only the description is always-loaded, and the SKILL.md body is loaded on invocation. The one exception is subagents with preloaded Skills, where the full SKILL.md body is injected at startup. For everyday usage, thinking in terms of “description always, body on demand” is an accurate enough mental model.

Skill Folder Layout — Only SKILL.md Is Required

Here’s the full directory structure a Skill can use. Everything except SKILL.md is optional.

.claude/skills/review/
├── SKILL.md              # REQUIRED: instructions (YAML frontmatter + Markdown)
├── scripts/              # OPTIONAL: executable scripts (Python / Bash / Node)
│   ├── lint.py
│   └── check-deps.sh
├── references/           # OPTIONAL: supplementary docs Claude reads on demand
│   ├── style-guide.md
│   └── security-checklist.md
└── assets/               # OPTIONAL: templates, fonts, images, output files
    ├── report-template.html
    └── logo.svg

Claude does not automatically read files in references/. Your SKILL.md body has to explicitly say “read security-checklist.md before running the review.” The scripts/ folder is where you put deterministic work — file conversion, schema validation, data aggregation — that benefits from actual code execution rather than LLM reasoning.

Design Principles — Composability and Portability

Anthropic’s guide calls out two design principles that shape how well your Skills play with others:

• Composability: Claude can load multiple Skills at once. Write Skills that coexist with others rather than assuming yours is the only one in play. Avoid framing instructions as “always do X, never do Y” unless you really mean it globally.
• Portability: A Skill written once runs identically on Claude.ai, Claude Code, and the Claude API. Write once, ship everywhere — as long as you don’t hardcode environment-specific dependencies.

Skills vs MCP vs Subagents — Don’t Confuse the Three

Skills get confused with MCP and Subagents all the time. They solve different problems and you often use all three together.

The three compose. Sentry’s published sentry-code-review Skill is a clean example: the Skill defines the PR review workflow (identify changes, correlate with errors, generate review comments), and the Sentry MCP server fetches the actual error logs and stack traces. The Skill owns “how,” MCP owns “what data.”

Skills vs Custom Commands

If you’ve been using Claude Code’s older Custom Commands (the .claude/commands/ directory with plain Markdown files), you might wonder how Skills differ. Here’s the breakdown:

The verdict: Use Skills for all new work. Custom Commands still function, but Skills are strictly more capable. If you have existing Custom Commands that work well, there’s no rush to migrate — but any new workflow should be a Skill.

Where Skills Live & Priority Order

Skills can be defined at three levels, and when multiple Skills share the same name, the most specific one wins:

1. Project Skills — .claude/skills/ in your repository root. Shared via Git with your team. Highest priority.
2. Global (User) Skills — ~/.claude/skills/ in your home directory. Personal Skills available across all projects.
3. Enterprise Skills — Provisioned by organization admins. Applied to all team members. Lowest priority (project Skills can override).

This layered approach means your team can establish baseline Skills at the enterprise level, individual developers can add personal productivity Skills globally, and each project can define specialized Skills that take precedence when you’re working in that codebase.

Writing SKILL.md — Frontmatter & Instructions

A SKILL.md file has two parts: YAML frontmatter (between --- delimiters) that configures behavior, and Markdown body that contains the actual instructions Claude will follow.

Basic Structure

Here’s a complete example — a code review Skill that checks for security issues, performance problems, and style violations:

---
name: review
description: "Performs a thorough code review focused on security, performance, and style"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff*)
  - Bash(git log*)
argument-hint: "[file-or-directory]"
---

# Code Review Skill

When invoked, perform the following review steps:

1. **Identify changed files** — Run `git diff --name-only HEAD~1` to find recently modified files,
   or use the argument if a specific path was provided.

2. **Security scan** — For each file, check for:
   - Hardcoded secrets, API keys, or tokens
   - SQL injection vectors (unsanitized inputs in queries)
   - XSS vulnerabilities (unescaped output in templates)
   - Insecure dependencies (check import statements)

3. **Performance review** — Look for:
   - N+1 query patterns
   - Missing database indexes (if schema files are present)
   - Unnecessary re-renders in React components
   - Large bundle imports that could be tree-shaken

4. **Style check** — Verify:
   - Consistent naming conventions
   - Functions under 50 lines
   - Proper error handling (no empty catch blocks)

5. **Output format** — Present findings as a Markdown checklist grouped by category,
   with severity labels: Critical, Warning, Suggestion.

Frontmatter Reference

Here’s every field available in the SKILL.md frontmatter:

Writing Effective Instructions

The body of your SKILL.md is where the real power lives. Here are the best practices for writing instructions that produce consistent, high-quality results:

Stay within the 500-token sweet spot. While there’s no hard limit on instruction length, Skills work best when the core instructions fit within about 500 tokens. Claude needs room in its context window for the actual work — code, file contents, and tool outputs. If your instructions are longer, consider splitting into a primary SKILL.md and supporting files referenced via the context field.

Use numbered lists for sequential steps. Claude follows numbered instructions more reliably than prose paragraphs. Each step should be a concrete, verifiable action:

1. Read the file specified in the argument
2. Identify all exported functions
3. For each function, check if a corresponding test exists in __tests__/
4. Generate tests for any untested functions
5. Run the test suite with `npm test` to verify

Leverage supporting files. For Skills that need reference data — style guides, template files, checklists — use the context frontmatter field to include additional files. These are loaded alongside your instructions when the Skill runs:

---
name: review
description: "Code review with project style guide"
context:
  - style-guide.md
  - security-checklist.md
---

# Review instructions here...
# Claude will have access to both supporting files.

Auto-Invocation — How Claude Loads Skills Automatically

One of the most powerful aspects of Skills is that Claude can invoke them without you typing the slash command. When you ask Claude to “review this PR” and you have a /review Skill, Claude recognizes the intent match and loads the Skill automatically. Here’s how the mechanism works under the hood.

Progressive Disclosure

When Claude Code starts a session, it scans all registered Skill folders and reads only the frontmatter from each SKILL.md. This costs roughly 100 tokens per Skill — cheap enough that even 50 registered Skills add less than 5,000 tokens to your startup context. The frontmatter gives Claude two critical pieces of information: the Skill name and its description.

As the conversation progresses, Claude evaluates each message against the registered Skill descriptions. When it finds a strong relevance match, it loads the full SKILL.md body into context and follows the instructions. This two-phase approach — scan, then load — means you get the discoverability of many Skills without the context cost of loading them all.

Controlling Auto-Invocation

You have three patterns for controlling when and how Skills activate:

Description Budget & Gotchas

Claude allocates approximately 1% of the total context window for Skill descriptions (fallback: 8,000 characters). On top of that, each individual description is truncated at 250 characters, so anything after that gets silently dropped. If you exceed the total budget, Claude prioritizes project-level Skills over global ones, and more recently used Skills over dormant ones.

You can adjust this budget by setting the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable. For example, to double the budget:

export SLASH_COMMAND_TOOL_CHAR_BUDGET=8000

Troubleshooting checklist when auto-invocation doesn’t fire:

• Is the description field present and descriptive? Claude relies on it for relevance matching.
• Is disable-model-invocation set to true? That blocks auto-invocation entirely.
• Are you over the description budget? Try reducing the number of registered Skills or increasing SLASH_COMMAND_TOOL_CHAR_BUDGET.
• Is your prompt clearly related to the Skill? Vague requests may not match. Try being more explicit.
• Check that the SKILL.md has valid YAML frontmatter — a missing --- delimiter will cause the entire file to be treated as instructions with no metadata.

Write “Pushy” Descriptions — Claude Defaults to NOT Triggering

If you want auto-invocation to actually work, the description field is where the battle is won or lost. Both Anthropic’s official guide and independent write-ups on implementing Skills converge on one non-obvious insight: Claude defaults to NOT triggering Skills. Left to its own devices, Claude tends to handle tasks directly rather than reaching for a Skill. To change that, your description needs to be explicit — almost “pushy” — about when the Skill should fire.

name: data-helper
description: A helper for data processing

name: sales-data-analyzer
description: Takes a sales CSV, decomposes KPIs into a tree, extracts prioritized insights, and generates an action plan. MUST be used for any request involving "sales analysis," "review of store data," or KPI exploration.

In practice, I don’t lean on auto-invocation as a primary pattern. I default to explicitly calling Skills with /skill-name and treat auto-invocation as a nice-to-have. If you do want it to fire, mentally simulate the prompts your users will actually type and ask yourself: “Would Claude read this and decide my Skill is the right tool?” That question will drive most of your description rewrites.

SKILL.md Length — Split at 500 Lines

There’s no hard cap on SKILL.md length, but a few rules of thumb keep your Skills performant:

• Official recommendation: Keep SKILL.md body under 5,000 words (roughly 15,000 tokens).
• Practical target: Stay under 500 lines. If you’re over, move reference material into references/ and point to it from SKILL.md (“read references/style-guide.md before generating output”).
• For auto-invocation-heavy Skills: Aim for under 300 tokens — the shorter the body, the tighter Claude’s adherence.

Long SKILL.md files dilute instruction-following. When your steps start to feel mushy, that’s your cue to split.

Let AI Draft, Then Review — My Authoring Workflow

Writing a SKILL.md from scratch feels harder than it is. My default workflow is to have AI draft the SKILL.md, then review and tighten it before shipping. A typical prompt I’d use: “I want a code review Skill focused on Python, emphasizing security and performance — draft the SKILL.md.” The AI produces a reasonable first cut, and I iterate from there.

The catch: if you leave AI to its own devices, you end up with a Skill that behaves differently from what you intended. When reviewing an AI draft, focus on these checks:

• Is the description pushy enough? Especially important if you want auto-invocation to work.
• Is allowed-tools narrowed? AI tends to grant broad Read/Write/Bash access by default — trim it to the minimum required.
• Are the steps concrete and deterministic? Replace “handle this appropriately” with the actual decision the Skill should make.
• Are side-effecting operations guarded? Anything that writes, commits, or deploys should usually set disable-model-invocation: true.

The lesson I’ve internalized: AI drafts are a shortcut, not a replacement for human review. A quick pass from a human raises the quality of the final Skill noticeably.

5 Practical Skills You Can Use Today

Before diving into the examples, it helps to know the three implementation patterns any Skill can fall into. The taxonomy — borrowed from a widely cited implementation write-up on Towards Data Science — makes it easier to pick the right shape for your use case.

Implementation Patterns — A, B, C

Here are five production-ready Skills covering common development workflows. Each one is designed to be dropped into your .claude/skills/ directory and used immediately.

---
name: review
description: "Code review for security, performance, and style"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff*)
  - Bash(git log*)
argument-hint: "[file-or-directory]"
---

1. Identify changed files via git diff or argument
2. Security: check for hardcoded secrets, injection, XSS
3. Performance: N+1 queries, missing indexes, bundle size
4. Style: naming, function length, error handling
5. Output as checklist with severity labels

---
name: tdd
description: "Test-driven development: Red, Green, Refactor"
argument-hint: "[feature-description]"
---

Follow the TDD cycle strictly:

1. RED — Write a failing test for the feature
   - Run the test to confirm it fails
   - The test must fail for the RIGHT reason

2. GREEN — Write the minimum code to pass
   - No extra logic, no premature optimization
   - Run the test to confirm it passes

3. REFACTOR — Clean up while keeping tests green
   - Extract functions, rename variables
   - Run tests after every change

Repeat for each sub-feature. Never skip red.

---
name: commit
description: "Generate Conventional Commits messages"
disable-model-invocation: true
allowed-tools:
  - Bash(git diff*)
  - Bash(git status*)
  - Bash(git log*)
  - Bash(git add*)
  - Bash(git commit*)
---

1. Run `git diff --staged` to see changes
2. If nothing staged, suggest files to add
3. Generate message: type(scope): description
   Types: feat, fix, docs, refactor, test, chore
   Body: explain WHY, not WHAT
4. Show message and wait for approval
5. Commit only after user confirms

---
name: translate
description: "Translate i18n locale files preserving keys"
model: opus
argument-hint: "[source-file] [target-language]"
context:
  - glossary.md
---

1. Read the source locale file (JSON/YAML)
2. Identify target language from argument
3. For each key-value pair:
   - Translate naturally (not literally)
   - Preserve interpolation: {name}, {{count}}
   - Maintain HTML tags if present
4. Cross-reference glossary.md for terms
5. Write translated file to correct path
6. Flag ambiguous translations for review

---
name: conventions
description: "Project coding standards and conventions"
user-invocable: false
---

When writing or modifying code in this project:

- TypeScript: strict mode, no `any`, prefer interface
- Naming: camelCase vars, PascalCase components,
  UPPER_SNAKE constants
- Errors: custom classes from src/errors/, no raw throws
- Imports: absolute @/ paths, group by type
- Tests: co-locate as *.test.ts, describe/it blocks
- Comments: only WHY, never WHAT
- Functions: max 30 lines, single responsibility

Testing & Iteration — A Skill Is Never “Done”

Writing the SKILL.md is only the first half of the work. Skills improve through iteration: you exercise them with real-looking prompts, watch how they behave, and tune the description and body until the Skill fires when you want it to and does what you expected.

Manual Testing — Throw Real-World Prompts at It

My personal testing loop is simple: after writing a Skill, I run it manually with prompts that look like what actual users would type. The important detail is that these prompts should be messy, not clean. Testing only with well-structured prompts produces Skills that crack the moment they meet production reality.

• Mix in typos and casual phrasing: “give this a once-over” instead of “perform a thorough code review.”
• Omit file names: “look at the API thing” instead of “review src/api.ts.”
• Add ambiguity: “make it better” — does the Skill bail out cleanly or does it misfire?

When I tune a description, I’m essentially asking “would a language model see this prompt and think to invoke the Skill?” If trigger rate is low, the usual fix is to add the missing vocabulary directly into the description.

skill-creator — Anthropic’s Official Tooling

Anthropic ships an official tool called skill-creator that automates most of the iteration loop:

• Splits your test prompts 60/40 into train and test sets to measure trigger rate objectively
• Generates multiple candidate descriptions and picks the one that scores highest
• Takes you from zero to a working Skill in 15–30 minutes

According to Anthropic’s guide, skill-creator solves most “my description isn’t triggering” problems without manual trial and error. If you’re about to spend an afternoon hand-tuning a Skill’s description, try skill-creator first.

The Iteration Loop

The full cycle I use for every new Skill:

1. Write: AI drafts the SKILL.md; I review and tighten.
2. Exercise: 5–10 realistic user prompts, manually executed.
3. Measure: Trigger rate, output accuracy, misfire rate.
4. Fix: Add missing keywords to the description, concretize mushy steps, tighten allowed-tools.

Team & Organization Deployment

Skills become truly powerful when shared across a team. Instead of each developer maintaining their own prompts and workflows, you can standardize on a shared set of Skills that everyone benefits from.

Project Skills (Git-Shared)

The simplest deployment path is committing your .claude/skills/ directory to your repository. Every team member who clones the repo gets the same Skills automatically. This is what I do in practice: I package development workflows and team rules as Skills, then distribute them via GitHub. The outcome I didn’t fully anticipate is that teammates start customizing the Skills to fit their own workflows, growing an ecosystem that maintains itself. “Ship a Skill and walk away” turns into “ship a Skill and watch it evolve.” That compounding effect is the real value of team distribution.

Concrete benefits of the Git-shared approach:

• Version controlled — Skill changes go through the same PR review process as code. You can see who changed what and why.
• Project-specific — Each repo can have Skills tailored to its stack, conventions, and workflows.
• Onboarding accelerator — New team members immediately get access to established workflows without reading a wiki.
• Standardization — Everyone follows the same review process, the same commit conventions, the same testing workflow.

A recommended directory structure for a team project:

.claude/
├── skills/
│   ├── review/
│   │   ├── SKILL.md
│   │   └── security-checklist.md
│   ├── tdd/
│   │   └── SKILL.md
│   ├── commit/
│   │   └── SKILL.md
│   ├── deploy-check/
│   │   ├── SKILL.md
│   │   └── deploy-requirements.md
│   └── conventions/
│       └── SKILL.md
└── CLAUDE.md

Enterprise Provisioning

For organizations on Claude Code’s Enterprise plan, administrators can deploy Skills to all team members through the admin dashboard. Enterprise Skills are ideal for:

• Compliance requirements — Ensure every developer follows security review procedures before submitting code.
• Code quality baselines — Enforce minimum standards across all repositories.
• Audit trails — Standardize commit messages and PR descriptions for regulatory compliance.
• Policy enforcement — Restrict tool usage across the organization (e.g., no direct production database access).

Enterprise Skills have the lowest priority in the resolution order, meaning project-level Skills can override them when necessary. This allows teams to customize while maintaining organizational baselines.

Distribution Channels — More Options Than Just Git

GitHub-based sharing is the default, but there are several other channels depending on the plan you’re on and where your Skills live.

Installing from the Plugin Marketplace

To pull in Anthropic’s curated Skill bundles from the command line:

# Add the marketplace
/plugin marketplace add anthropics/skills

# Install Document Skills (docx/pdf/pptx/xlsx)
/plugin install document-skills@anthropic-agent-skills

# Install Example Skills (frontend design, creative, etc.)
/plugin install example-skills@anthropic-agent-skills

Always skim the SKILL.md of a third-party Skill before installing — see the security section below for why.

Pre-Ship Checklist

Security Considerations

Troubleshooting — Common Issues & Fixes

Here are the three most common issues developers encounter when setting up Skills, along with their solutions.

FAQ — Claude Code Skills