Claude Code Skills Documentation: Complete Reference

Claude Code's skills system lets you extend the agent with custom workflows defined in SKILL.md files. The official documentation covers the basics but leaves gaps around advanced patterns, skill composition, and debugging. This guide fills those gaps with practical examples.

Quick Answer: Claude Code skills are SKILL.md markdown files stored in ~/.claude/skills/ that define custom workflows the agent follows automatically. Each skill has YAML frontmatter (name, description, version) and markdown instructions. Claude reads all installed skills at session start and activates the relevant one based on your request. Browse 1,500+ ready-made skills at agensi.io/skills.

Claude Code's skills system is one of the most powerful features in any AI coding agent. But the official documentation gives you the format without the patterns. This guide covers what the docs do not: how to structure skills for complex workflows, how skills interact with each other, how to debug skills that are not activating, and how to optimize skill instructions for consistent output.

Where are Claude Code skills stored?

Skills live in ~/.claude/skills/ as .md files. Claude reads every file in this directory at the start of each session. You can organize skills into subdirectories. Claude scans recursively. For detailed platform-specific paths, see where are claude skills stored.

What is the SKILL.md format?

Every skill starts with YAML frontmatter followed by markdown instructions:

---
name: my-skill
description: One line describing when this skill should activate
version: 1.0.0
---

# My Skill

## When to use this skill
Activate when the user asks for help with [specific task].

## Workflow
1. Step one
2. Step two
3. Step three

## Output format
[Define the expected output structure]

The description field is critical. Claude uses it to decide when to activate the skill. Make it specific: "Activate when the user asks for a code review of a pull request" not "Helps with code."

How do I install skills from Agensi?

# Download and extract to the skills directory:
unzip keyword-research.zip -d ~/.claude/skills/

Start a new Claude Code session. The skill appears automatically. Browse 1,500+ skills on Agensi.

How do multiple skills work together?

Claude reads all installed skills and activates the most relevant one based on your request. If you have a code review skill and a testing skill installed, asking "review this PR and add tests" activates both. Skills do not conflict as long as their description fields target different tasks.

For advanced composition, see Claude Code skills bundle guide.

Why is my skill not activating?

Three common causes. First, the description does not match your request. Claude matches your words against skill descriptions. Be explicit. Second, the skill file has a syntax error in the YAML frontmatter. Validate with a YAML linter. Third, the file is not in the right directory or has the wrong extension. Must be .md in ~/.claude/skills/. For more troubleshooting, see the skills not working guide.

How do I write better skill instructions?

Be specific, not vague. "Write clean code" is useless. "Follow the Airbnb JavaScript style guide, use early returns, limit functions to 20 lines, and add JSDoc comments to exported functions" is actionable. Include examples of expected output. Claude follows examples more consistently than abstract rules.

Browse skill examples on Agensi.