What are Claude Skills?

Claude Skills are a way to teach Claude how to do a specific task once, then have it reach for those instructions automatically every time the task comes up. A skill is just a folder on disk. It lives under .claude/skills/ in your project or under ~/.claude/skills/ as a personal global available across every project. Inside that folder is a SKILL.md file with a short frontmatter block describing what the skill does and when to use it, followed by the actual instructions written in plain Markdown. You can add as many supporting files as you want: scripts the skill calls, example outputs, prompt templates, reference data, or even sample inputs Claude can study before doing the real task.

The key word is autonomous. You do not have to remember to invoke a skill. Claude scans the available skill descriptions and decides on its own whether a skill applies to what you just asked for. If it matches, the skill loads and Claude follows it. If it does not match, the skill stays out of the way and does not eat context. That selective loading is the difference between a tidy assistant and one buried in instructions it does not need this turn.

The problem skills solve

Every team accumulates institutional knowledge that lives in someone's head or in a stale Notion page nobody reads. How we write commit messages. How we structure a blog post. How we set up a new microservice. How we run the deploy checklist. How we name database migrations. Without skills you re-prompt Claude every time, or you cram everything into CLAUDE.md and watch the context window balloon while the model gets fuzzier as it tries to weigh too many simultaneous instructions. With skills you write the playbook once, save it next to the code, and Claude pulls it in only when the relevant kind of work is actually happening.

That shift turns Claude from a fast intern who needs constant reminding into something closer to a coworker who has read the handbook. The handbook is even better than a real one because it executes itself. You will notice the difference the first time a new contributor opens the repo and Claude already knows your conventions.

How skills actually work

A SKILL.md starts with YAML frontmatter. The two fields that matter most are name and description. The description is the single most important line in the whole file. Claude uses it to decide whether to invoke the skill, so it should clearly state what the skill does and when to use it. A weak description is the number one reason skills fail to fire when you expect them to. Below the frontmatter is freeform Markdown. Write it the way you would brief a new hire: here is the goal, here are the steps in order, here are the gotchas, here is what good output looks like, here is what bad output looks like.

When Claude Code starts a session, it scans your skill directories and indexes the descriptions. While you work, Claude compares incoming tasks against those descriptions. If it sees a match, it loads the full SKILL.md into context along with any files the skill points to. The supporting files in the folder are not loaded automatically. They are referenced from inside the SKILL.md, so you can keep large examples or scripts on disk and only pull them in when needed. That keeps the skill light when its body is short and powerful when its body needs to expand.

Skills compose. A skill can reference other skills. A blog-writer skill can reference a house-style skill. A deploy skill can reference a checklist skill. You get the same modularity you would get in a well-factored codebase, applied to instructions instead of functions.

Real skills builders write

A few examples that show up in real projects, including in the templates we share inside Claude Code Club at claudecodeclub.ai:

• blog-writer - house style, voice rules, byline conventions, and a structure template for new posts, plus a short list of forbidden words.
• commit-style - how to format commits, when to squash, what counts as a breaking change, and what the subject line cap is.
• pr-review - checklist for self-reviewing a pull request before requesting human review, including security and accessibility passes.
• migration-runner - exact steps to write, test, and apply a database migration in this codebase, with rollback notes.
• diagram-gen - a workflow that calls a local script to produce branded infographics in the right style and color palette.
• incident-response - the on-call playbook with links to runbooks, alert dashboards, and the right Slack channel for each service.
• release-notes - the structure and tone used to summarize what shipped in the last week, including how to credit contributors.

Each of those used to live in someone's notes. As a skill, it travels with the repo, is reviewed in pull requests like any other code, and applies automatically the next time the situation comes up. That is the version-controlled muscle memory promise made real.

Common misconceptions

Skills are not plugins. They do not add new tools or change what Claude can technically do at the protocol level. They shape behavior, not capability. Tools come from the CLI itself and from MCP servers. Skills tell Claude how to use the tools it already has well, in the specific context where they matter.

Skills are not magic prompts that turn a small model into a big one. If a task is genuinely beyond the model, no skill will fix that. Skills shine on tasks the model already can do, where consistency, following your conventions, and not forgetting steps matter more than raw reasoning. That is where most repeat work in a codebase actually lives.

Skills are not invoked by you in the typical case. Beginners often try to type 'use the blog-writer skill.' You can, but the point is to let Claude pick them up on its own based on the description. Write descriptions that make that easy and you stop having to remember which skills you even have.

Skills are not a replacement for testing. A skill can describe the deployment checklist but cannot guarantee the deployment is safe. You still run the tests, still review the diff, still make the call.

How to write your first skill

1. 1Pick a task you have asked Claude to do more than twice the same way. Repetition is the signal.
2. 2Create .claude/skills/your-skill-name/SKILL.md in your project root.
3. 3Add YAML frontmatter with a name and a tight description that says what triggers the skill in plain language.
4. 4Write the body the way you would brief a thoughtful new teammate. Include the steps, the standards, and one short example of a good outcome.
5. 5Reference any supporting files by relative path. Add them to the same folder so the skill is self-contained.
6. 6Test it. Start a new Claude Code session and ask for the kind of task the skill targets. Confirm Claude picks it up without being asked.
7. 7Refine the description until invocation is reliable. A vague description is the most common reason skills do not trigger when you expect them to.
8. 8Commit the skill. Treat it as code, because that is what it has become.

When not to use a skill

Do not write a skill for a one-time task. The whole point is repetition, and writing a skill costs more than just prompting if you only need it once. Do not write a skill that duplicates CLAUDE.md. Project-wide conventions belong in CLAUDE.md so they always apply. Skills are for situations where the instructions are only useful when a specific kind of work is happening, like 'writing a blog post' or 'running a migration.'

Avoid skills that are mostly tool definitions. If the heart of what you want is a new capability, the right answer is usually an MCP server, not a skill. Use a skill to teach Claude how to use that server well in your codebase. The two together are more powerful than either alone, and the boundary between them is clear once you have seen it.

Writing descriptions that actually trigger

Most skill problems are description problems. The description is the only field Claude reads when deciding whether to load the skill, so a vague description means the skill never fires when you expect it to. The fix is to write descriptions that name the task and the trigger together. 'Writes a blog post in house style' is okay. 'Use this when the user asks to write, draft, or outline a blog post for the company blog' is better. The verbs and triggers tell Claude exactly when the skill applies.

If a skill is not triggering, look at the description first. Read it as if you were a model with no context, scanning a long list of candidate skills. Would you pick this one for the task you just asked about? If the answer is unclear, rewrite the description until it is obvious. That single habit fixes most of the frustration newcomers have with skills.

Personal vs project skills

Skills come in two flavors that solve different problems. Project skills live in your repo under .claude/skills and ship with the codebase. They encode conventions specific to that project: how its database is structured, how its API is laid out, how its team writes pull requests. Anyone who clones the repo gets the skills automatically. They are part of the project's institutional memory.

Personal skills live in ~/.claude/skills and apply across every project you work on. They encode habits you carry with you: how you like commit messages to read, how you take notes during a session, how you prefer to structure new directories. Personal skills are the place to capture your own taste so it follows you from repo to repo without polluting any single project's history.

Use both. Start with personal skills for your habits, project skills for the codebase's conventions, and resist the urge to push personal preferences into project skills where other contributors would inherit them by accident. The separation keeps both layers clean.

How skills fit the broader ecosystem

Skills, MCP servers, and CLAUDE.md form a clean three-layer setup. CLAUDE.md holds project-wide context that always applies. MCP servers expose live tools to the outside world. Skills are the on-demand playbooks that tie behavior to specific situations. Put them together and Claude Code starts feeling less like a chatbot and more like a teammate who has been on the team for years. For $9/mo, claudecodeclub.ai ships a working library of skills you can drop into your own repos to skip the first few weeks of trial and error, then customize as you learn what your stack actually needs.

The thing nobody tells you is that good skills compound. Each one you write makes the next session faster, which means you get more done, which means you have more chances to notice repeatable patterns worth turning into the next skill. After a few months the codebase feels like it operates itself for the routine work and your attention finally lands on the work that actually needs you. That is the promise people had for AI tools five years ago, and skills are most of what makes it real now.