Claude Code Skill Guide: Build & Deploy Custom Skills (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 each time is inefficient. Claude Code Skills let you encode these workflows into /slash-commands that execute with a single invocation. I’ve created and actively use multiple Skills in my own workflow, and they’ve dramatically sped up repetitive tasks. I also recommend distributing them to team members for standardized workflows — and if you get stuck writing one, just ask AI for help. In this guide, you’ll learn what Skills are, how to write SKILL.md, how auto-invocation works behind the scenes, five practical examples you can copy into your project today, and how to deploy Skills across your team.

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.

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 2% of the total context window for Skill descriptions. For a 200k context window, that’s about 4,000 tokens — enough for roughly 40 Skills with well-written descriptions. If you exceed this budget, Claude will prioritize 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.

5 Practical Skills You Can Use Today

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

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 approach has several advantages:

• 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.

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

Summary — Make Claude Code Your Own

Here’s what you should take away from this guide:

• Skills are folder-based slash commands defined in .claude/skills/<name>/SKILL.md with YAML frontmatter and Markdown instructions.
• Progressive disclosure keeps things efficient — only frontmatter is loaded at startup (~100 tokens per Skill), with full instructions loaded on demand.
• Auto-invocation matches intent to Skills so Claude can load the right workflow without you typing the slash command.
• Nine frontmatter fields give you fine-grained control over invocation behavior, tool access, model selection, and execution mode.
• Team sharing is as simple as a git commit — put Skills in your repo and everyone benefits.
• Security matters — use allowed-tools, review third-party Skills, and never store secrets in SKILL.md.

I started with just one Skill and now use several daily. Start with your most repetitive workflow — code review, commit messages, testing — and encode it. Once you see how much time it saves, you’ll want to Skill-ify everything.

👉 15 Claude Code Efficiency Tips — Keyboard Shortcuts, Flags & Workflow Hacks

👉 Claude Code Security Setup Guide — Permissions, Sandboxing & Safe Defaults

👉 Claude Code CLI vs Web vs Desktop — Which Interface Should You Use?

📖 Related Articles Mentioned

Claude Code Efficiency: 15 Proven Techniques (2026)Claude Code Security Settings: 9 Proven Steps [2026]Claude Code CLI vs Web vs Desktop: Ultimate Comparison (2026)Claude Code Commands Cheat Sheet — Complete Reference (2026)Claude Pricing Plans: Which One Is Actually Worth It? (2026)Claude Cowork Automation — 5 Real Use Cases (2026)

Author

krona23

Over 20 years in the IT industry, serving as Division Head and CTO at multiple companies running large-scale web services in Japan. Experienced across Windows, iOS, Android, and web development. Currently focused on AI-native transformation. At DevGENT, sharing practical guides on AI code editors, automation tools, and LLMs in three languages.

DevGENT about →