What are skills?

Every time you explain your team's coding standards to Claude, you're repeating yourself. Every PR review, you redescribe how you want feedback structured. Every commit message, you remind Claude of your preferred format. Skills fix this.

A Skill is a markdown file that teaches Claude how to do something once, so Claude applies that knowledge automatically whenever it's relevant. No slash commands to remember, no instructions to paste. You write the procedure down in one place, and Claude reaches for it when the task shows up.

What skills actually are

Skills are folders of instructions that Claude Code can discover and use to handle tasks more accurately. Each skill lives in a SKILL.md file with a small YAML frontmatter block — a name and a description — followed by the actual instructions Claude should follow.

Here's the minimum a skill needs:

---
name: pr-review
description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
---

When reviewing a PR:
1. Check for unhandled error paths
2. Flag any new dependencies and explain why they were added
3. Summarise risk in one sentence at the top of the review

The description field is load-bearing. It's how Claude decides whether to pull the skill in at all. When you ask Claude to review a PR, it compares your request against every available skill's description and activates the ones that match. Your instructions — the body of the file — only get loaded after a match.

Where skills live

You store skills in one of two places, depending on who needs them.

Personal skills go in ~/.claude/skills. They follow you across every project on your machine — your commit message style, your preferred documentation format, how you like code explained. On Windows, that's C:/Users/<your-user>/.claude/skills.

Project skills go in .claude/skills inside the root of your repository. Anyone who clones the repo gets them automatically. This is where team standards live: brand guidelines, preferred fonts and colours, security review checklists, the framework conventions your company enforces.

Project skills get committed to version control alongside your code, so the whole team shares them without any extra install step.

Skills vs. CLAUDE.md vs. slash commands

Claude Code has several ways to customise behaviour. Skills are the one that's both automatic and task-specific, and it helps to see them next to the alternatives.

CLAUDE.md loads into every conversation, always. If you want Claude to use TypeScript strict mode across an entire project, that belongs in CLAUDE.md. It's your always-on project contract.

Skills load on demand, and only when they match. Claude reads just the name and description at startup, so your PR review checklist doesn't sit in context while you're debugging a failing test. It loads the moment you actually ask for a review, and not before.

Slash commands require you to type them. They're explicit. Skills aren't — Claude reaches for them when it recognises the situation, without being told.

The practical consequence: CLAUDE.md is where always-true constraints go. Slash commands are for things you want to invoke deliberately. Skills are for expertise you want Claude to apply automatically, but only when it's relevant.

The skill-waiting-to-be-written heuristic

Skills work best for specialised knowledge that applies to specific tasks — code review standards your team follows, commit message formats you prefer, brand guidelines for your organisation, documentation templates for particular kinds of docs, debugging checklists for a specific framework.

The rule of thumb is simple. If you find yourself explaining the same thing to Claude repeatedly, that's a skill waiting to be written. Capture the instructions once, put them behind a good description, and Claude will reach for them every time the task comes up.