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.

Skills also solve the context budget problem. The more experienced you get at using the claude code CLI, the more you accumulate a body of best practices specific to your codebase. Piling all of those into one CLAUDE.md file would consume a large slice of the available context on every turn, even when the current task has nothing to do with, say, database migration naming. Skills scope that knowledge to the moment it is actually needed, which keeps every turn lean and keeps the model's attention focused on what matters right now.

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.

Listing synonyms and common phrasings in the description also helps. If the task is 'write a migration' some people say 'create a migration', others say 'add a database change', others say 'schema update'. A description that mentions all three variants triggers more reliably than one that locks onto a single phrase. Breadth of trigger phrasing is the skill writing equivalent of keyword coverage in SEO, both serve the same purpose: make the match easier when the language varies.

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.

Skills and the learn claude code by doing principle

One of the best arguments for skills is that writing them makes you a better builder. The act of articulating exactly what makes a good commit message, or exactly what steps a safe database migration follows, forces you to think more precisely about the craft than you would if you were just doing it by feel. Skills are not only instructions for Claude. They are documentation of your own thinking, written in a form that Claude can execute. That dual purpose means they compound in value over time.

When you learn claude code by doing - which is the only way that actually sticks - you will write your first skill badly. The description will be too vague. The steps will skip a subtlety. The example output will be off-brand. That is fine. The first draft exists to be improved by the second session where the skill fails to do what you expected. Treat each failed invocation as a test failure with a clear fix: read the description, read the task, find the mismatch, narrow the description. After three or four rounds you will have a skill that works reliably and the instinct for how to write the next one well from the start.

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.