Claude Code Skills Guide (SKILL.md)

Create and use Claude Code skills: SKILL.md structure, frontmatter fields, load locations, automatic and /skill-name invocation, and bundled skills (2026).

Need an API key? Sign up →·Endpoints & base URLs →

Last verified: 2026-10-20 · 📄 Per official docs (Claude Code Skills)

A skill is a SKILL.md file: YAML frontmatter between --- markers that tells Claude when to use it, plus Markdown instructions Claude follows when it runs. Claude uses skills when they are relevant, or you can invoke one directly with /skill-name.

Skills are knowledge-layer components in Claude Code that provide domain-specific expertise and guidance to Claude. Claude loads them automatically when relevant, and you can also invoke one directly with /skill-name.

What are Skills?¶

Skills are professional knowledge modules stored in SKILL.md files:

• Auto-activation: Claude automatically uses relevant Skills based on task context

• Domain knowledge: Provides best practices and guidance for specific domains

• Extensible: Create custom Skills to meet specific needs

• Context-aware: Only invoked in relevant scenarios

Skills vs Commands vs Agents¶

Skills, commands, and CLAUDE.md (verified 2026-10-20)¶

Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools. Custom commands have been merged into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it.

Using Built-in Skills¶

Claude Code plugins typically include multiple built-in Skills. When your task matches a Skill's description, Claude automatically uses it.

Claude Code also includes a set of bundled skills, such as /doctor, /code-review, /batch, /debug, /loop, and /claude-api (verified 2026-10-20). You invoke a bundled skill the same way as any other skill: type / followed by the skill name.

Example: Code Review¶

When you say "help me review this code for security issues", if a plugin with a security review Skill is installed, Claude will automatically apply that Skill's knowledge for the review.

Viewing Available Skills¶

Skills are typically installed with plugins:

# Install plugin (plugins may contain multiple Skills)
/plugin install plugin-name@marketplace

Creating Custom Skills¶

Basic Structure¶

The simplest Skill only needs a SKILL.md file:

my-skill/
└── SKILL.md

SKILL.md Format¶

---
name: Code Style Guide
description: Use this skill when the user asks about "code style", "naming conventions", "code formatting", or discusses coding standards
---

# Code Style Guide

## Naming Conventions

- Variables use camelCase
- Constants use UPPER_SNAKE_CASE
- Classes use PascalCase
- Private members use underscore prefix

## Formatting Rules

- Use 2 spaces for indentation
- Line width should not exceed 80 characters
- Use trailing commas

## Best Practices

- Functions should have single responsibility
- Avoid deep nesting
- Use meaningful variable names

Frontmatter Fields¶

All fields are optional. Only description is recommended, so Claude knows when to use the skill; name can be omitted and defaults to the directory name. A field name must match the official frontmatter reference exactly, hyphens included (the table below lists only common fields; the official docs also cover model, effort, hooks, user-invocable and more): Claude Code ignores a field it doesn't recognize without reporting an error (verified 2026-10-20).

version is not a field in this table: Claude Code ignores a field it does not recognize, without reporting an error (verified 2026-10-20).

Writing Effective Descriptions¶

The description field determines when a Skill is activated and should include specific trigger phrases:

Good example:

description: Use this skill when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events

Bad example:

description: Guide about hooks  # Too vague

Complete Skill Structure¶

For complex Skills, you can include more resources:

my-skill/
├── SKILL.md           # Main knowledge document
├── references/        # Detailed references
│   ├── patterns.md    # Design patterns
│   └── advanced.md    # Advanced techniques
├── examples/          # Example code
│   ├── basic.ts       # Basic example
│   └── advanced.ts    # Advanced example
└── scripts/           # Helper scripts
    └── validate.sh    # Validation script

Referencing Resources¶

Reference other resources in SKILL.md:

---
name: API Development Guide
description: Use when the user asks about "API design", "REST interfaces", "API best practices"
---

# API Development Guide

See @references/patterns.md for detailed API design patterns

## Quick Example

See @examples/basic.ts for basic usage

Dynamic context injection¶

A line such as !`git diff HEAD` uses dynamic context injection: Claude Code runs the command and replaces the line with its output before Claude sees the skill content, so the instructions arrive with the current diff already inlined (verified 2026-10-20).

Where skills load¶

• Personal skills live in ~/.claude/skills/<skill-name>/SKILL.md.
• Project skills live in .claude/skills/<skill-name>/SKILL.md inside the repository.
• Plugin skills live in <plugin>/skills/<skill-name>/SKILL.md inside the plugin.

Using Skills in Plugins¶

Directory Structure¶

Skills go in the plugin's skills/ directory:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/          # Command layer
├── agents/            # Agent layer
└── skills/            # Knowledge layer
    ├── code-style/
    │   └── SKILL.md
    └── api-docs/
        ├── SKILL.md
        └── references/

Referencing Skills in Commands¶

Commands can explicitly reference Skill knowledge:

---
description: Generate standards-compliant API documentation
argument-hint: [api-file]
---

Generate API documentation for @$1.

Use the api-docs skill to ensure documentation includes:

- Complete endpoint descriptions
- Parameter specifications
- Response formats
- Error codes
- Usage examples

Practical Examples¶

Example 1: Project Standards Skill¶

---
name: Project Standards
description: Use when the user asks about "project structure", "file organization", "directory conventions"
---

# Project Standards

## Directory Structure

\`\`\`
src/
├── components/    # React components
├── hooks/         # Custom Hooks
├── services/      # API services
├── utils/         # Utility functions
└── types/         # TypeScript types
\`\`\`

## File Naming

- Components: PascalCase (e.g., `UserProfile.tsx`)
- Utilities: camelCase (e.g., `formatDate.ts`)
- Constants: UPPER_SNAKE_CASE (e.g., `API_ENDPOINTS.ts`)

## Import Order

1. React related
2. Third-party libraries
3. Internal modules
4. Type definitions
5. Style files

Example 2: Git Workflow Skill¶

---
name: Git Workflow
description: Use when the user asks about "branch strategy", "commit conventions", "Git process"
---

# Git Workflow Standards

## Branch Naming

- Features: `feature/description`
- Fixes: `fix/description`
- Hotfixes: `hotfix/description`

## Commit Message Format

\`\`\`
<type>(<scope>): <subject>

<body>

<footer>
\`\`\`

### Type Values

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation update
- `style`: Code formatting
- `refactor`: Refactoring
- `test`: Testing
- `chore`: Build/tooling

Example 3: Security Review Skill¶

---
name: Security Review
description: Use when the user asks about "security check", "vulnerability scan", "security best practices", or reviewing code security
---

# Security Review Guide

## Common Vulnerability Checks

### SQL Injection

- Check for parameterized queries
- Avoid string concatenation in SQL

### XSS Attacks

- Check if user input is escaped
- Use CSP headers

### Sensitive Data

- Ensure passwords are not stored in plaintext
- Don't hardcode API keys
- Check logs for sensitive data leaks

## Review Checklist

- [ ] Input validation
- [ ] Output encoding
- [ ] Authentication mechanism
- [ ] Authorization checks
- [ ] Encryption usage
- [ ] Error handling

Best Practices¶

1. Clear Trigger Descriptions¶

Use specific trigger phrases, not vague descriptions:

# Good
description: Use when the user asks about "create component", "React component template", "component best practices"

# Bad
description: React component related

2. Structured Knowledge¶

Organize knowledge into clear hierarchies:

• Use heading levels

• Provide code examples

• Include checklists

3. Keep Updated¶

• Regularly update Skill content

• Version numbers reflect changes

• Document important updates

4. Modular Design¶

• Each Skill focuses on one domain

• Use references directory for detailed materials

• Provide practical examples

Debugging Skills¶

If a Skill isn't activating as expected:

1. Check description: Ensure trigger phrases match user input

2. Verify format: Ensure YAML frontmatter is correctly formatted

3. Test triggers: Try using exact phrases from the description

Next Steps¶

• Plugin System - Learn complete plugin development

• MCP Servers - Extend Claude's tool capabilities

• CLI Tips - Improve command-line efficiency

Enterprise →