The Skills System

Table of content

Skills are reusable instructions that teach Claude how to approach specific tasks. Instead of repeating the same prompts, you define them once and invoke by name.

What skills do

Without skills	With skills
Repeat same instructions every time	Invoke by name: `/brainstorm`
Forget your preferred approach	Consistent methodology
Long prompts for complex tasks	Clean, composable capabilities
Context lost between sessions	Persistent knowledge

Built-in vs custom

Claude Code ships with built-in skills. You can also create your own.

Type	Location	Examples
Built-in	Bundled with Claude Code	`brainstorm`, `write-plan`, `systematic-debugging`
Custom	`.claude/skills/` in your project	Your team’s review process, project-specific workflows
Shared	`~/.claude/skills/`	Personal skills across all projects

List available skills:

claude "/help"  # Shows available slash commands and skills

Skill file structure

Skills live in .claude/skills/{skill-name}/skill.md:

.claude/
└── skills/
    └── research/
        └── skill.md

The skill.md file:

---
name: research
description: Deep research on any topic with source verification
---

# Research Skill

When researching a topic:

1. Start with authoritative sources
2. Cross-reference claims
3. Note contradictions
4. Summarize findings with citations

## Output format

- **Summary**: 2-3 sentences
- **Key findings**: Bullet points
- **Sources**: Links with credibility notes
- **Gaps**: What couldn't be verified

Frontmatter fields

Field	Required	Purpose
`name`	Yes	How to invoke the skill
`description`	Yes	When to use (shown in help, triggers auto-selection)

Creating your first skill

mkdir -p .claude/skills/quick-review

Create .claude/skills/quick-review/skill.md:

---
name: quick-review
description: Fast code review focusing on bugs and security issues
---

# Quick Review

Review code for critical issues only. Skip style nitpicks.

## Checklist

- [ ] Security vulnerabilities (injection, auth bypass)
- [ ] Null/undefined access
- [ ] Resource leaks (unclosed connections, listeners)
- [ ] Race conditions
- [ ] Error handling gaps

## Output format

| Issue | Severity | Line | Fix |
|-------|----------|------|-----|

If no issues: "No critical issues found."

Test it:

claude "/quick-review src/auth.ts"

Example: Research skill

For thorough investigation of technical topics:

---
name: research
description: Deep research with source verification and gap analysis
---

# Research Skill

## Process

1. **Scope**: Define what we're researching and why
2. **Search**: Find authoritative sources (docs, papers, official repos)
3. **Verify**: Cross-reference claims across sources
4. **Synthesize**: Combine into actionable knowledge

## Source hierarchy

| Priority | Source type | Trust level |
|----------|-------------|-------------|
| 1 | Official docs | High |
| 2 | GitHub repos | High |
| 3 | Technical blogs | Medium |
| 4 | Stack Overflow | Verify |
| 5 | AI summaries | Low |

## Output

### Summary
2-3 sentence answer to the research question.

### Key findings
- Finding 1 [source]
- Finding 2 [source]

### Contradictions
Note any conflicting information found.

### Gaps
What couldn't be verified or needs more research.

### Sources
Full list with credibility assessment.

Example: Refactoring skill

For systematic code improvements:

---
name: refactor
description: Systematic refactoring with safety checks and verification
---

# Refactoring Skill

Safe, incremental code improvements.

## Pre-flight

- [ ] Understand current behavior (read tests, run code)
- [ ] Identify what changes and what stays same
- [ ] Check test coverage for affected code

## Process

1. **Small steps**: One change at a time
2. **Test after each**: Run tests before next change
3. **Preserve behavior**: Refactoring != feature changes

## Checklist

- [ ] All tests pass before starting
- [ ] Each change is a single commit
- [ ] No behavior changes (unless explicitly requested)
- [ ] Types still compile
- [ ] No new warnings

## If tests fail

Stop. Show what broke. Ask before proceeding.

## Output per step

| Step | Change | Tests | Commit |
|------|--------|-------|--------|

Example: Documentation skill

For consistent, useful docs:

---
name: document
description: Generate clear documentation following project conventions
---

# Documentation Skill

Write docs people actually read.

## Principles

- **Scannable**: Headers, bullets, tables
- **Examples first**: Show, then explain
- **No fluff**: Cut "In order to", "It should be noted that"
- **Assume competence**: Skip obvious explanations

## Structure by type

### Function/Method

Brief description (one line).

@param name - what it is @returns what comes back @throws when it fails @example code here


### README

Name

One-line description.

Quick start

3 commands max.

API

Table of main functions.

Examples

Real use cases.


### API endpoint

POST /endpoint

Brief description.

Request

Response

| Field | Type | Description |

Example

curl command


## Anti-patterns

| Don't | Do |
|-------|-----|
| "This function is used to..." | "Validates user input" |
| Document obvious params | Document non-obvious behavior |
| Copy implementation | Explain intent |

Auto-triggering

Skills can trigger automatically based on their description. When you ask Claude something that matches a skill’s description, it may invoke that skill.

Your request	Matched skill
“Research how X works”	`research`
“Review this PR for issues”	`quick-review`
“Add docs to this function”	`document`

You can also invoke explicitly:

claude "/research WebSocket authentication patterns"
claude "/refactor this module to use async/await"

Skill with todos

Checklists in skills become interactive todos:

## Pre-deployment checklist

- [ ] All tests pass
- [ ] No console.logs
- [ ] Environment variables documented
- [ ] Migration scripts tested
- [ ] Rollback plan documented

Claude tracks these as it works, marking items complete.

Project-wide vs personal

Scope	Location	Use case
Project	`.claude/skills/`	Team workflows, project conventions
Personal	`~/.claude/skills/`	Your preferences across all projects

Project skills override personal ones with the same name.

Debugging skills

If a skill isn’t working:

Check the path: .claude/skills/{name}/skill.md
Verify frontmatter has name and description
Test explicit invocation: claude "/{skill-name}"
Check for syntax errors in markdown

Next: Custom Commands

Topics: claude-code automation workflow