getting-started

## Overview

Skills are the core building blocks of Claude Code plugins. A skill is a single markdown file named `SKILL.md` that tells Claude *how* to perform a specific task -- code review, database migration, security scanning, or anything else you can express in structured instructions. When Claude detects that your request matches a skill's trigger conditions, it loads the skill automatically and follows its methodology.

This guide explains the anatomy of a SKILL.md file, walks you through building one from scratch, and shows how to test and refine it until it performs reliably.

## What is a SKILL.md file

A SKILL.md file lives inside a plugin at `skills/<skill-name>/SKILL.md`. It contains two parts:

1. **YAML frontmatter** -- metadata that tells Claude Code when and how to load the skill.
2. **Markdown body** -- the actual instructions Claude follows when the skill activates.

Here is a minimal example:

```markdown
---
name: quick-lint
description: |
  Run a fast lint check on the current file. Use when the user asks
  to lint, check style, or fix formatting issues.
allowed-tools: Read, Bash(npx:eslint)
version: 1.0.0
author: Your Name <you@example.com>
license: MIT
---

## Overview

You are a code linting specialist. When activated, run ESLint on the
target file and report results in a structured format.

## Steps

1. Identify the file to lint from the user's request.
2. Run `npx eslint <file> --format stylish` using the Bash tool.
3. Parse the output and summarize findings.
4. If there are auto-fixable issues, offer to run `npx eslint <file> --fix`.
```

When a user says "lint this file" or "check the formatting," Claude matches those phrases against the skill's `description` field and loads the instructions.

## Frontmatter schema

Every SKILL.md starts with a YAML frontmatter block delimited by `---`. The following fields are supported.

### Required fields

| Field | Type | Description |
|---|---|---|
| `name` | string | Unique identifier for the skill (kebab-case) |
| `description` | string | When to use this skill. Include trigger phrases that Claude matches against. |
| `allowed-tools` | string | Comma-separated list of tools the skill can use |
| `version` | string | Semantic version (e.g., `1.0.0`) |
| `author` | string | Author name and optional email |
| `license` | string | SPDX license identifier (e.g., `MIT`, `Apache-2.0`) |

### Optional fields

| Field | Type | Description |
|---|---|---|
| `model` | string | Override the LLM model (`sonnet`, `haiku`, `opus`) |
| `context` | string | Set to `fork` to run in a subagent context |
| `agent` | string | Subagent type (e.g., `Explore`) |
| `user-invocable` | boolean | Set to `false` to hide from the `/` menu |
| `argument-hint` | string | Autocomplete hint shown in the `/` menu |
| `hooks` | object | Lifecycle hooks (e.g., `pre-tool-call`) |
| `compatibility` | string | Environment requirements (e.g., `Node.js >= 18`) |
| `compatible-with` | string | Platform compatibility (`claude-code`, `cursor`) |
| `tags` | array | Discovery tags for search and categorization |

### The `description` field matters most

The `description` is the single most important field. Claude uses it to decide whether to activate the skill. Write it as a natural-language explanation of *when* the skill should fire, including specific trigger phrases:

```yaml
description: |
  Perform a security audit on JavaScript or TypeScript code. Use when the
  user asks to check for vulnerabilities, audit security, scan for XSS,
  or review authentication logic.
```

Poor descriptions that are too vague ("helps with code") or too narrow ("only for React useState hooks") cause skills to either fire too often or never fire at all.

### The `allowed-tools` field

This field is a whitelist of the tools Claude is permitted to use when the skill is active. Valid tools:

```
Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch,
Task, TodoWrite, NotebookEdit, AskUserQuestion, Skill
```

You can scope `Bash` to specific commands for tighter security:

```yaml
allowed-tools: Read, Edit, Bash(npm:*, npx:*, git:status)
```

This allows the skill to run any `npm` or `npx` command and `git status`, but nothing else.

## Markdown body structure

The body after the frontmatter closing `---` is the instruction set Claude follows. Use standard markdown with clear section headings.

### Recommended sections

A well-structured skill body includes these sections:

```markdown
## Overview
What this skill does and its core methodology.

## Steps
Numbered step-by-step procedure Claude follows.

## Output
The format and structure of the skill's output.

## Constraints
Boundaries, edge cases, and things to avoid.

## Examples
Concrete input/output examples that calibrate Claude's behavior.
```

You do not need every section in every skill. A simple linter skill might only need Overview and Steps. A complex security auditor benefits from all five.

### Writing effective instructions

Skills are prompt engineering. The same principles that make a good system prompt make a good skill body:

- **Be specific.** "Review the code" is weak. "Check for SQL injection, XSS, CSRF, insecure deserialization, and broken authentication" is strong.
- **Use numbered steps.** Claude follows numbered procedures more reliably than prose paragraphs.
- **Show the output format.** If you want structured output, include a template or example.
- **Set boundaries.** Tell Claude what *not* to do. "Do not modify files unless explicitly asked" prevents unwanted side effects.

### Referencing supporting files

Skills can reference other markdown files in the same skill directory using relative links:

```markdown
For the complete API reference, see API docs.
For usage examples, see examples.
```

Claude follows these links using the `Read` tool when it needs the referenced content. This keeps your main SKILL.md focused while allowing deep-dive documentation in supporting files.

For bash commands or dynami