Skills

Skills are reusable prompt templates stored in .claude/skills/. They turn your team’s best practices into one-command workflows.

What skills are

A skill is a SKILL.md file inside a named folder under .claude/skills/. When Claude detects that a skill is relevant to your request, it loads the skill’s instructions and follows them. Skills encode institutional knowledge so that every engineer on the team can produce consistent, high-quality output.

Identifying skill opportunities

Any task you do more than twice the same way is a skill candidate:

Skill design patterns

Template skills

Template skills generate files from a pattern:

# SKILL.md for generate-endpoint

## Purpose
Generate a new REST API endpoint following our team's conventions.

## Input
The skill expects $ARGUMENTS to contain:
- Resource name (e.g., "products")
- HTTP methods to support (e.g., "GET, POST, PUT, DELETE")

## Output
Generate the following files:
1. src/routes/{resource}.ts — route handler
2. src/services/{resource}Service.ts — business logic
3. src/schemas/{resource}.ts — Zod validation schemas
4. src/tests/{resource}.test.ts — test file with skeleton tests

## Conventions
- Follow the patterns in src/routes/users.ts as the template
- Use our standard error handling from src/shared/errors.ts
- All routes must use the requireAuth middleware
- Tests must use our test utilities from src/tests/helpers.ts

Analysis skills

Analysis skills investigate and report:

# SKILL.md for security-audit

## Purpose
Perform a security-focused review of a specified module.

## Input
$ARGUMENTS contains the path to the module to audit.

## Process
1. Use subagents to check in parallel:
   - Authentication: Are all endpoints properly protected?
   - Authorization: Is data access scoped to the right users?
   - Input validation: Are all inputs validated and sanitized?
   - Data exposure: Is PII protected in logs, errors, and responses?
   - Dependencies: Are there known vulnerabilities in dependencies?

2. For each finding, classify severity: CRITICAL / HIGH / MEDIUM / LOW

## Output Format
Produce a markdown report with sections for each category.
Include file paths and line numbers for every finding.

Workflow skills

Workflow skills encode multi-step processes:

# SKILL.md for new-feature

## Purpose
Guide the implementation of a new feature through our standard workflow.

## Process
1. EXPLORE: Investigate the relevant areas of the codebase
2. PLAN: Propose 2-3 implementation approaches with tradeoffs
3. DECIDE: Wait for the engineer to choose an approach
4. IMPLEMENT: Code the solution in stages, pausing for review
5. TEST: Generate tests covering happy paths and edge cases
6. COMMIT: Create a conventional commit with a clear message

Do NOT skip the explore and plan phases. Do NOT implement without approval.

Sharing skills across the team

Skills in .claude/skills/ are committed to the repo. The entire team gets them automatically. This means:

• A senior engineer writes a skill once
• Every engineer on the team can invoke it
• The skill encodes institutional knowledge (naming conventions, patterns, standard libraries) that would otherwise live in someone’s head
• Junior engineers produce senior-quality output by following the skill’s template

How skills are loaded

Skills use a two-stage loading model that keeps Claude’s context efficient:

Stage 1 — Descriptions (always in context): Skill descriptions are loaded into context so Claude knows what’s available. This is how Claude decides whether a skill is relevant to the current request.

Stage 2 — Full content (loaded when invoked): The full skill content only loads when the skill is actually invoked, either by you (via /skill-name) or by Claude when it determines the skill is relevant. Supporting files in the skill directory are available for Claude to read as needed during execution.

your-skill-name/
  SKILL.md              # Required — instructions and frontmatter
  scripts/              # Optional — executable scripts
  references/           # Optional — docs loaded as needed
  examples/             # Optional — example outputs

Writing effective skill descriptions

The description field is the most important part of any skill. It determines when Claude loads and activates the skill. Get it wrong, and your skill never fires (or fires when it should not).

Guidelines:

• Include both WHAT the skill does and WHEN to use it
• Add specific trigger phrases users would say
• Keep descriptions concise — one to two sentences that help Claude decide when the skill is relevant
• Avoid markup or complex formatting in the description — plain text works best

Good example:

---
name: migration-generator
description: >
  Generate database migration files. Use when the user asks to
  create a migration, add a table, modify a column, add an index,
  or change the database schema. Also use when the user says
  "migrate", "schema change", or "add column".
---

Debugging tip: Ask Claude “When would you use the migration-generator skill?” and it will quote the description back, revealing exactly what it understood.

Advanced frontmatter fields

Beyond name and description, skills support these fields:

Running skills in isolation

Add context: fork to run a skill in a separate subagent context. The skill content becomes the prompt that drives the subagent:

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

This is useful for skills that need to explore broadly without filling up your main conversation context.

Critical rules for skill files

• SKILL.md must be exactly that name (case-sensitive — not skill.md or Skill.md)
• Folder must be kebab-case (my-skill-name, not mySkillName)
• Do NOT put a README.md inside the skill folder
• Keep SKILL.md under 500 lines — move detailed reference material to separate files
• For critical validations, use scripts — code is deterministic, instructions are not

Capability skills vs. preference skills

A useful mental model for thinking about skills (not official terminology):

Capability skills extend what Claude can do:

• PDF extraction, form filling, image generation
• Integration with specific APIs or tools
• Complex multi-step workflows

Preference skills encode how you want Claude to work:

• Meeting note formatting, documentation standards
• Code review checklists, commit message conventions
• Response style preferences

Both benefit from testing, but the testing strategy differs. Capability skills need functional correctness tests. Preference skills need consistency checks.

Iterating on skills

A suggested practice: treat skill development like software engineering.

1. Create — Build the initial skill from a clear specification
2. Evaluate — Define test cases with specific inputs and expected outputs
3. Improve — Analyze failures, revise instructions based on data
4. Regression-check — Run the full test suite after every change to catch regressions

This is not a formal workflow from the official docs, but it maps well to how prompt engineering works in practice.

Skills ecosystem

Official skill examples and the Agent Skills specification are available at https://github.com/anthropics/skills. The repository includes template skills, document creation skills, and patterns for various use cases.

Check the official Claude Code documentation for the latest information on skill features and ecosystem developments.

Browse the repository for patterns and inspiration before building from scratch.