Claude CodeEvery time you start a new conversation with Claude, you start from scratch, re-explaining your preferences, workflow, and project context. Skills solve this. A skill is a set of instructions, packaged as a simple folder, that teaches Claude how to handle specific tasks or workflows. You teach Claude once and benefit every time.
The anatomy of a skill
A skill is a folder with this structure:
your-skill-name/
├── SKILL.md ← Required: your instructions
├── scripts/ ← Optional: Python, Bash, etc.
├── references/ ← Optional: docs loaded on demand
└── assets/ ← Optional: templates, fonts, iconsThe only mandatory file is SKILL.md. A skill can be as simple as a single markdown file or as complex as a folder with scripts and reference documentation. Most skills start simple and grow.
Here's what a minimal SKILL.md looks like:
---
name: code-reviewer
description: Reviews pull requests using our team's coding standards.
Use when user says "review this PR", "check my code", or "code review".
---
# Code Reviewer
## Instructions
When reviewing code, always check for:
1. Proper error handling (no bare catch blocks)
2. TypeScript strict mode compliance
3. Test coverage for new functionsThat's a working skill. The YAMLWhat is yaml?A human-readable text format used for configuration files, including Docker Compose and GitHub Actions workflows. frontmatter tells Claude when to activate it, and the markdown body tells Claude what to do.
SKILL.md filename is case-sensitive. Files named skill.md, Skill.md, or Skills.md will not be recognized.When are skills worth building?
Skills shine when you have repeatable workflows: the overhead of creating one only pays off when you'll use it multiple times. Here are the clearest use cases:
- Document generation: Create reports, specs, or presentations that always follow your team's style guide
- Code reviews: Analyze pull requests using your organization's specific standards
- Research workflows: Run investigations with consistent methodology every time
- MCPWhat is mcp?Model Context Protocol - a standard that lets AI tools connect to external services like databases, issue trackers, or APIs. enhancement: Turn raw APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. access into guided, optimized workflows
- Onboarding: Teach Claude how to explain your codebase to new team members
- Data processing: Apply consistent transformation and validation rules to incoming data
| Situation | Skill worth it? | Why |
|---|---|---|
| You review PRs the same way every week | Yes | Repeatable, consistent criteria needed |
| You generate weekly status reports | Yes | Same format, different data each time |
| You need to debug one specific issue | No | One-off task, just use a conversation |
| You're exploring a new API you've never used | No | Too early to know the workflow |
| Your team onboards 3 engineers per quarter | Yes | Same walkthrough every time |
| You write SQL migrations following strict rules | Yes | Consistent patterns, easy to mess up |
Rule of thumb: if you do something more than three times, build a skill. If you only do it once, a regular conversation is more efficient.
SKILL.md file. Add complexity only when you hit a real limitation.Skills vs. prompts
How is a skill different from a system promptWhat is system prompt?Hidden instructions set by the developer that shape how an AI assistant behaves throughout a conversation. Users don't see it, but it defines the AI's persona and constraints. or a long message you paste at the start of every chat?
| System prompt | Skill | |
|---|---|---|
| Scope | One conversation | Works across all sessions |
| Loading | Always loaded | Loaded only when relevant |
| Token cost | Always pays full cost | Progressive, pays only what's needed |
| Distribution | Hard to share | Shareable folder |
| Versioning | Copy-paste | Files in a folder, can use git |
| Maintenance | Update everywhere manually | Update once, works everywhere |
The key advantage is selective loading. Claude only loads a skill's full instructions when the task is relevant. If you have a code review skill and a sprint planning skill, Claude only loads the code review instructions when you ask for a code review. This keeps tokenWhat is token?The smallest unit of text an LLM processes - roughly three-quarters of a word. API pricing is based on how many tokens you use. usage efficient even with dozens of skills installed.
Where skills work
Once you build a skill, it works identically across:
- Claude.ai: upload via Settings > Capabilities > Skills
- Claude Code: place in the Claude Code skills directory
- APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses.: available for programmatic use
Write it once, use it everywhere. Anthropic treats skills as an open standard, similar to how MCPWhat is mcp?Model Context Protocol - a standard that lets AI tools connect to external services like databases, issue trackers, or APIs. works across different AI tools.
How skills actually save time
Consider writing a weekly engineering status report. Without a skill, every Monday you re-explain your report format, data sources, and tone to Claude, 10-15 minutes of setup before Claude even starts writing. With a weekly-report skill, you just say "write this week's status report" and Claude already knows everything. Setup time drops to zero.
Real-world examples
Skills that real teams use daily:
- Design system enforcer: Ensures generated UI code uses the company's component library with correct tokens, spacing, and ARIAWhat is aria?Accessible Rich Internet Applications - HTML attributes (like aria-label and aria-hidden) that give extra information to screen readers when native HTML elements can't do the job. attributes
- Incident responder: Walks through a runbookWhat is runbook?A documented, step-by-step guide for responding to a specific production incident. when a production alert fires, checking logs, identifying the failing service, drafting a status update
- Release notes writer: Pulls recent commits, categorizes changes by type, and generates release notes in the team's standard format
- APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. documentation generator: Reads endpointWhat is endpoint?A specific URL path on a server that handles a particular type of request, like GET /api/users. code and produces OpenAPIWhat is openapi?A standard format for describing REST APIs - their endpoints, parameters, and response shapes. Tools can generate documentation and client libraries from it automatically.-compliant documentation with request/response examples
- Interview prep: Generates coding interview questions tailored to the role level, with rubrics for consistent evaluation
Each of these would take 10-15 minutes to explain from scratch. With a skill, Claude jumps straight to execution.