What Are Claude Code Skills? A Plain-English Guide

Claude Code skills are folders holding a SKILL.md file of instructions that Claude loads on demand. Each skill teaches one repeatable workflow. Claude scans four locations, personal, project, plugin, and built-in, reads every description at startup, and loads only the matching skill when a task needs it.

Most pages that rank for this question are vendor docs: one exhaustive reference manual and one product FAQ. Neither was written by someone whose week depends on these files. I run a local SEO agency on automation, and my own outreach system sends about 200 form submissions a day with follow-up running behind it as a skill file. This is the operator version of what those files are.

TL;DR

• A Claude Code skill is a folder with a SKILL.md file. YAML frontmatter says when to use it, markdown instructions say what to do.
• Claude reads every description at startup, about 100 tokens per skill, and loads the full file only when your task matches. That is progressive disclosure.
• Skills live in four places: personal ~/.claude/skills/, project .claude/skills/, plugins, and bundled skills like /code-review.
• Custom slash commands have merged into skills. CLAUDE.md keeps holding facts. Skills hold the procedures.

How does a Claude Code skill work?

A Claude Code skill works through progressive disclosure. Claude reads each skill’s name and description at startup, about 100 tokens per skill, and loads the full SKILL.md only when a task matches the description. Extra files load last, only when the instructions call for them.

That is the whole mechanism, in three levels: metadata loading at startup, activation when the task fits, resource loading when a script or reference file is needed. Because only descriptions sit in context permanently, you can keep dozens of skills installed for almost no token cost until one fires.

After activation, the rendered skill stays in context for the rest of the session, so a skill you invoked ten minutes ago still shapes what Claude does now.

I keep two kinds of skills in my own setup. Knowledge skills like my Review Response Engine fire automatically, because their descriptions match requests I actually type. Anything that acts on the outside world stays manual: my Proposal and Quote Writer runs only when I type its slash command, locked with disable-model-invocation: true, because a proposal leaving the building is my call, not the model’s.

The description is the trigger. If it does not match the words you type, the skill never fires.

What is the SKILL.md format for Claude Code skills?

Every skill is one SKILL.md file with two parts. YAML frontmatter between --- markers carries the name and description fields, and markdown below it gives Claude the instructions. Every frontmatter field is optional, and only description is recommended.

The smallest useful example takes two minutes. Make the folder ~/.claude/skills/summarize-changes/, and inside it write a SKILL.md that opens like this: a line with ---, then a line starting description: that reads Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed., then --- again, then plain markdown instructions. That is the entire file. Ask what did I change and Claude loads it on its own, or type /summarize-changes to fire it directly.

The directory name becomes the command, and the description decides when it loads unprompted, per how Claude Code loads skills.

Frontmatter can pull in live data too. A line reading !`git diff HEAD` tells Claude Code to run that command before the skill reaches the model and paste the output in place. The docs call it dynamic context injection, and it means Claude sees your actual diff instead of guessing from open files.

Keep the file lean. The combined description and when_to_use text gets truncated at 1,536 characters in the skill listing, and the docs recommend keeping SKILL.md under 500 lines. Heavy material moves into references/, scripts/, and assets/ folders beside the main file, loaded only when needed. The step-by-step build, frontmatter to first test, is in create your own Claude Code skill.

Frontmatter tells Claude when to load the skill. The body tells it what to do. Mix those up and neither job gets done.

Where are Claude Code skills stored on disk?

Claude Code scans four locations: personal skills at ~/.claude/skills/<skill-name>/SKILL.md, project skills at .claude/skills/<skill-name>/SKILL.md, plugin skills inside an enabled plugin, and bundled skills shipped with the CLI. Personal skills reach all your projects, and project skills stay in one repository.

Precedence matters when names collide. An enterprise managed setting overrides a personal skill, a personal skill overrides a project skill, and a skill at any level overrides a bundled skill with the same name. Plugin skills dodge collisions entirely with a namespace, so a deploy skill inside my-plugin becomes /my-plugin:deploy and runs beside your own. Nested project folders work the same way: a skill in apps/web/.claude/skills/ shows up as apps/web:deploy.

Day-to-day management is almost nonexistent. Claude Code watches skill folders and picks up edits in the current session, no restart, unless you created a brand-new top-level skills directory. Skills enabled on your claude.ai account download into ~/.claude/skills/synced/ when syncing is switched on. See where Claude Code skills are stored for the full location table.

I split my own skills the same way the docs split storage. My personal level holds cross-job habits, like the Anti-Slop Humanizer that strips AI tells out of any draft in any project. Project level holds anything tied to one codebase, so the skills driving my SEO pipeline ride inside that pipeline’s own repository.

Storage location is access control. Pick the folder by who should get the skill, not by habit.

How is a skill different from a prompt, slash command, or CLAUDE.md in Claude Code?

A prompt is one instruction you type once. A skill is a file Claude reloads every time the task matches. A slash command is now just a skill you invoke by name. CLAUDE.md holds standing facts that load every session whether or not they are relevant.

	Prompt	Slash command	Skill	CLAUDE.md
What it is	One typed instruction	A skill invoked by name	A folder teaching one workflow	Standing project notes
Where it lives	Your message	.claude/commands/ or .claude/skills/	.claude/skills/<name>/SKILL.md	Repo root or home config
When it loads	Consumed immediately	When you type /name	When the task matches the description	Every session
Best for	Quick one-offs	Deliberate triggers	Repeated procedures	Facts, not steps

The slash command column is mostly historical. Custom commands merged into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, old command files keep working, and when both exist the skill wins.

Two neighbors stay different. An MCP server connects Claude to an external service, per the official skills overview. A hook fires a script on session or tool events. Neither one teaches a repeatable workflow the way a skill file does.

The paste test settles the choice for me:

• Typed it once, it stays a prompt.
• Typed it twice this week, it becomes a skill.
• Needed in every session already, it belongs in CLAUDE.md.
• Reacts to events rather than requests, that is a hook’s job.
• Talks to outside software, that is an MCP server’s job.

My own CLAUDE.md files hold facts: audience, positioning, voice rules. The day a section turns into numbered steps, it migrates into a skill. Anyone selling a decade of agent experience will not tell you that the barrier is this low.

If you keep pasting it, it wants to be a skill. If Claude needs it every single session, it belongs in CLAUDE.md.

Do skills work with Claude Code subagents?

Add context: fork to a skill’s frontmatter and Claude runs it in a subagent. The skill body becomes the subagent’s prompt, with no access to your conversation history. The run executes in the background by default and delivers the result when it finishes.

That makes forks the right home for long or messy jobs: a full code review, a deep research pass, a bulk edit you do not want narrated into your main thread. Set background: false if you would rather wait for the result in the same turn. The docs cover the details under run skills in a subagent. Invocation is controllable from both directions:

Frontmatter	You can invoke	Claude can invoke	Description in context
Default	Yes	Yes	Yes
disable-model-invocation: true	Yes	No	No
user-invocable: false	No	Yes	Yes

Those invocation control fields pair with allowed-tools, which pre-approves specific tools for the turn that invokes the skill. The grant clears on your next message even though the skill content stays loaded.

My review agent works this way in production. It reads a finished manuscript as a forked run, so a full QA pass never bloats the writing session that ordered it, and its verdict lands as a message when done.

Fork a skill when the job is long or dirty. Keep it inline when the conversation needs the context.

What are good examples of Claude Code skills?

Good skills wrap one repeated procedure. Claude Code bundles /doctor, /code-review, /debug, /batch, /loop, and /claude-api. Anthropic ships document skills for Excel, Word, PowerPoint, and PDF, partners like Notion and Figma publish theirs, and individual operators write their own.

The bundled skills prove the format scales down as well as up: /verify simply confirms a code change does what it should. On the hosted side, the same overview lists Anthropic-built, partner-built, organization-provisioned, and fully custom skills, so a Team administrator can push one skill to everyone at once. For community favorites worth installing today, I ranked the best ready-made Claude Code skills separately.

Mine are working examples rather than exhibits. Thirteen live in the skills bundle: a sales group (Proposal and Quote Writer, Cold Email and Follow-Up Cadence, Review Request System, Objection Handler), a delivery group (GBP Optimization Audit, Review Response Engine, Citation Builder, SOP Builder), and a quality-plus-plumbing group (Skill Creator, Anti-Slop Humanizer, Skills Menu, Session Handoff, Skill Runtime Builder). Every one started as a procedure I was tired of repeating.

AutomateReal skills

This post is an example too. An autonomous SEO pipeline wrote it: researcher, planner, copywriter, reviewer, publisher, one skill file each. I built the team, and its reviewer agent rejects any draft that misses the format rules, which keeps my own consistency out of the equation.

The best example is the workflow you did manually three times this month. Write that one next.

AutomateReal services

For a managed version, see the skills bundle.

Related: sell claude skills (make money with claude skills)

FAQ

How do I install a skill into Claude Code?

Installation is a folder copy. Drop the skill folder into ~/.claude/skills/ for personal use or .claude/skills/ for one project, and Claude Code picks it up in the current session through live change detection. Only a brand-new top-level skills directory needs a restart.

There is no registry and no config file to edit. To remove a skill, delete its folder. The one exception is a skill synced from claude.ai: switch it off on your account and the next sync removes the local copy.

Can I use the same skill in Claude Code, claude.ai, and the API?

The file travels, the extras do not. SKILL.md follows the Agent Skills specification, published as an open standard at agentskills.io, so the same folder works on any platform that adopts it. Claude Code features like context: fork and dynamic context injection stay Claude Code only.

Packaging enforces the boundary. Uploading to claude.ai accepts only the spec’s six fields, name, description, license, compatibility, metadata, and allowed-tools, and an unexpected field fails with a hard error instead of being ignored.

Are Claude Code skills free, or do they need a paid plan?

A skill costs nothing to write. It is a folder you create yourself, and bundled skills like /debug arrive with Claude Code in every session. On claude.ai, the skills feature requires a Pro, Max, Team, or Enterprise plan, because it depends on code execution.

So the honest split is: building and using skills locally is a format, not a purchase. The hosted document and partner skills are the part gated behind plans.

What makes a good skill description?

A good description states the use case first, in the exact words you type when you need the skill. It is the main field Claude matches against, it shares a 1,536-character listing cap with when_to_use, and vagueness is the number one reason a skill never fires.

The first description I ever wrote listed what the file contained. Nothing in it matched my requests, so Claude read the listing and shrugged. The rewrite opened with use when, spelled out the trigger phrases, and the skill started firing on its own. Write the description for the person asking, not for the author.

---

If you want help finding that first workflow worth turning into a skill, a discovery call maps it in about thirty minutes.