guides

## What Is a Skill?

A skill is an auto-activating instruction file that Claude Code loads when its trigger conditions are met. Unlike slash commands (which the user must explicitly invoke) or agents (which run as autonomous sub-agents), skills activate automatically based on context. They live at `skills/[skill-name]/SKILL.md` inside a plugin directory and contain YAML frontmatter followed by Markdown instructions.

Skills are the most common building block in the Tons of Skills ecosystem. Of the 2,834 skills available on the [marketplace](/explore), the vast majority are SKILL.md files that enhance Claude Code's behavior for specific tasks: code review, deployment, API integration, testing, and more.

This guide walks you through building a skill from scratch, covering every decision you need to make along the way.

## Step 1: Plan Your Skill

Before writing any Markdown, answer these questions:

**What problem does this skill solve?** A good skill addresses a repeatable task that benefits from structured instructions. "Help me write unit tests for React components" is a good scope. "Do everything related to my project" is too broad.

**When should this skill activate?** Claude Code reads the `description` field to decide when to load your skill. Think about the exact phrases a developer would say or the context that should trigger activation.

**What tools does Claude need?** Every tool you grant is a permission. Grant only what the skill actually requires. A skill that reads configuration files needs `Read` and `Glob` but probably not `Write` or `Bash`.

**What is the expected output?** Define what success looks like. A code review skill should produce structured feedback. A deployment skill should produce a checklist with pass/fail status.

### Planning Checklist

Write down:

1. A one-sentence purpose statement
2. Three to five trigger phrases users might say
3. The minimum set of tools required
4. The expected output format
5. Any prerequisites (runtime, language, framework)

## Step 2: Create the Directory Structure

Skills live inside a plugin at `skills/[skill-name]/SKILL.md`. The skill name must be lowercase kebab-case.

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── README.md
└── skills/
    └── react-test-writer/
        ├── SKILL.md
        ├── patterns.md          # Optional supporting file
        └── examples/
            └── component.test.tsx  # Optional example file
```

Create the directory:

```bash
mkdir -p skills/react-test-writer
touch skills/react-test-writer/SKILL.md
```

## Step 3: Write the Frontmatter

The YAML frontmatter block at the top of SKILL.md configures how Claude Code discovers and loads your skill. Here is the complete set of fields:

```yaml
---
name: react-test-writer
description: |
  Write comprehensive unit tests for React components using Testing Library
  and Vitest. Trigger phrases: "write tests for this component", "add unit
  tests", "test this React component", "generate component tests".
allowed-tools: Read, Write, Edit, Bash(npx vitest:*), Glob, Grep
version: 1.0.0
author: Your Name <you@example.com>
license: MIT
compatible-with: claude-code
tags: [testing, react, vitest, unit-tests]
---
```

### Required Fields

| Field | Purpose |
|-------|---------|
| `name` | Unique identifier in kebab-case. Must match the directory name. |
| `description` | Tells Claude Code when to activate this skill. Include trigger phrases. This is the single most important field for discoverability. |
| `allowed-tools` | Comma-separated list of tools the skill may use. |
| `version` | Semantic version string. |
| `author` | Name and optional email. |
| `license` | SPDX license identifier. |

### Optional Fields

| Field | Purpose | Example |
|-------|---------|---------|
| `model` | Override the LLM model. | `sonnet`, `haiku`, `opus` |
| `context` | Run in a forked sub-agent. | `fork` |
| `agent` | Sub-agent type when context is fork. | `Explore` |
| `user-invocable` | Set to `false` to hide from the slash menu. | `false` |
| `argument-hint` | Autocomplete hint shown in the slash menu. | `"<component-path>"` |
| `hooks` | Lifecycle hooks for pre/post tool calls. | `{ pre-tool-call: ... }` |
| `compatibility` | Runtime requirements. | `"Node.js >= 18"` |
| `compatible-with` | Platform compatibility. | `claude-code, cursor` |
| `tags` | Discovery tags for search and categorization. | `[testing, react]` |

### Writing a Strong Description

The `description` field is a paragraph, not a sentence. Claude Code uses it as the primary signal for auto-activation. Follow these rules:

1. Start with a verb phrase: "Write", "Analyze", "Deploy", "Generate"
2. Describe the specific task clearly
3. List three to five trigger phrases users might say
4. Mention key technologies or frameworks

**Good description:**

```yaml
description: |
  Write comprehensive unit tests for React components using React Testing
  Library and Vitest. Covers render tests, user interaction tests, async
  behavior, and snapshot tests. Trigger phrases: "write tests for this
  component", "add unit tests", "test this React component".
```

**Bad description:**

```yaml
description: "Helps with testing"
```

## Step 4: Choose Your Allowed Tools

The `allowed-tools` field implements the principle of least privilege. Only grant the tools your skill actually needs.

### Available Tools

| Tool | Purpose | When to Include |
|------|---------|-----------------|
| `Read` | Read files from disk | Almost always needed |
| `Write` | Create new files | When generating new files |
| `Edit` | Modify existing files | When updating existing files |
| `Bash` | Execute shell commands | When running CLI tools |
| `Glob` | Find files by pattern | When searching for files by name |
| `Grep` | Search file contents | When searching inside files |
| `WebFetch` | Fetch URLs | When pulling remote data |
| `WebSearch` | Search the web | When looking up documentation |
| `Task` | Create sub-tasks | For complex mul