Claude Code skills, explained

Skills are the simplest way to make Claude Code reliably good at something specific: a folder with a SKILL.md file that teaches the agent a workflow, from "review PRs the way our team does" to "generate release notes from git history". No code required, though skills can bundle scripts when they need them.

What a skill actually is

A skill is a directory containing a SKILL.md markdown file with frontmatter (a name and a description) followed by instructions. Optionally it ships supporting files: scripts the skill can run, reference documents it can load, and assets it uses in output. The description matters more than it looks: Claude Code reads it to decide when the skill applies.

---
name: conventional-commits
description: Write commit messages following the Conventional Commits spec. Use when committing changes.
---

When writing commit messages:
1. Use the format: type(scope): description
...

Where skills live

• Personal skills: ~/.claude/skills/<skill-name>/ apply across all your projects.
• Project skills: .claude/skills/<skill-name>/ ship with the repository, so the whole team gets them on checkout. Project skills are the underrated half: they turn tribal knowledge into something the agent applies on every run.
• Plugin skills: plugins can bundle skills, which is how larger toolkits distribute them.

How skills get used

Two paths:

1. Implicit: Claude Code matches your request against skill descriptions and applies the relevant one automatically. This is the main mode and the reason to write precise descriptions.
2. Explicit: name it in your prompt ("use the code-review skill on this diff") when you want a specific skill to fire.

Skills compose with the rest of the extension surface: hooks for hard guarantees the model cannot skip, MCP servers for external data and tools, and plugins to package all of it. The rule of thumb: instructions and workflow knowledge belong in skills; deterministic enforcement belongs in hooks; external integrations belong in MCP.

Finding good skills

Anthropic maintains an official catalog at anthropics/skills on GitHub, and the wider ecosystem has grown fast. We index and verify skills continuously: browse skills for Claude Code in our directory, where each listing shows provenance and which agents it works with.

Worth knowing: the skill format is becoming portable across agents. Many skills written for Claude Code run in Codex and other agents that read the same SKILL.md shape, so a good skill is increasingly a write-once asset. See how skills work in Codex for the other side.

Writing your first skill

Start from a real annoyance: something you have explained to Claude Code three times this month. Then:

1. Create the folder and SKILL.md (personal first, promote to the project later).
2. Write the description as a trigger condition, not a slogan: "Use when reviewing database migrations" beats "Database expert".
3. Keep instructions concrete and stepwise; link reference files rather than pasting walls of context.
4. Test by asking for the task naturally, without naming the skill, and confirm it fires.

Treat skills like code: review them in PRs, version them with the repo, and prune ones that stopped earning their place. And before installing anything from the wild, read what it does; a skill is instructions your agent will follow with your permissions.

Sources: Claude Code skills docs and anthropics/skills, checked June 2026.