You keep pasting the same long prompt into Claude Code. The brand voice rules, the SEO checklist, the “always add an FAQ” reminder. Every session starts from zero, and every session you forget one line.
Skills fix that. This guide explains what a skill is, what sits inside the SKILL.md file, how Claude decides to use one, where skills live on your machine, and how they differ from CLAUDE.md, slash commands, subagents, MCP servers and plugins. It also lists where to find good skills, free and paid, with links and star counts checked on 1 November 2026.
The primary source throughout is Anthropic’s own documentation at code.claude.com/docs/en/skills. Where we lean on community sources, we say so.
What are Claude Code skills? The short definition
A Claude Code skill is a folder containing a SKILL.md file: a short block of YAML frontmatter that tells Claude when to use it, followed by Markdown instructions Claude follows when it runs. Claude loads a skill automatically when your request matches its description, or you call it yourself by typing /skill-name.
Anthropic’s docs put it in one line: “Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit.”
That is the whole idea. A skill is a saved playbook. It can be ten lines (“write meta descriptions between 140 and 160 characters, front-load the keyword, no clickbait”) or a full workflow with reference files and scripts beside it.
Why a folder and not just a prompt?
Because the folder can hold more than words. A typical skill directory looks like this:
seo-brief/
├── SKILL.md ← required: frontmatter + instructions
├── reference.md ← optional: detailed rules, loaded only when needed
├── examples.md ← optional: sample outputs
└── scripts/
└── word-count.sh ← optional: a script Claude can runOnly SKILL.md is required. Everything else is optional support material.
Skills are an open format
Claude Code skills follow the open Agent Skills standard, which Anthropic’s docs reference directly. Claude Code adds its own extensions on top, such as invocation control and running a skill inside a subagent. In practice this means many skills you find on GitHub also work in other agent tools that read the same format, though the Claude Code extras will not.
Takeaway: if you can write a checklist, you can write a skill.
What is inside a SKILL.md file?
A SKILL.md file has two parts. YAML frontmatter between --- markers, which must start on the first line, and a Markdown body with the instructions. The description field matters most, because Claude reads it to decide when the skill applies.
Here is a small, realistic example for a content team:
---
name: meta-description
description: Writes SEO meta descriptions. Use when the user asks for a meta description, SERP snippet, or search preview text for a page.
---
# Meta description writer
1. Ask for the page URL or draft if none is given.
2. Write 3 options, each 140 to 160 characters.
3. Put the primary keyword in the first 60 characters.
4. No exclamation marks, no "click here".
5. Show the character count after each option.The frontmatter fields worth knowing
Anthropic’s docs list more fields than most people need. These are the ones that change behaviour:
| Field | What it does |
|---|---|
name | The command name. Defaults to the folder name. |
description | Recommended. Claude uses it to decide when to load the skill. |
when_to_use | Extra trigger context, appended to the description. |
disable-model-invocation | true stops Claude loading it on its own. You must type /name. |
user-invocable | false hides it from the / menu, so only Claude can use it. |
allowed-tools | Tools Claude may use without asking, for that turn only. |
context: fork | Runs the skill in a separate subagent with its own context. |
paths | Glob patterns that limit automatic loading to matching files. |
Two details from the docs trip people up. First, field names must match exactly; unknown fields are ignored without an error. Second, if the YAML fails to parse, the skill still loads but with no fields set, so your description silently disappears. If a skill “never fires”, check the frontmatter first.
The docs also note that description plus when_to_use is truncated at 1,536 characters in the skill listing. Write the trigger phrases early.
The body: write it like a brief for a sharp freelancer
The Markdown body is plain instructions. Numbered steps, rules, examples, a definition of done. Anthropic recommends keeping SKILL.md under 500 lines and moving detailed reference material into separate files. That advice connects to the most important idea in the whole system: progressive disclosure.
step-by-step guide to building your first skill
How progressive disclosure keeps skills cheap
Progressive disclosure means Claude loads skills in layers. At the start of a session it only sees each skill’s description. The full SKILL.md body loads when the skill is used, and supporting files load only if the instructions point to them and the task needs them.
This is why you can install dozens of skills without stuffing Claude’s context window. In the docs’ words: “Full skill content only loads when invoked.”
Think of it as three layers:
| Layer | What loads | When |
|---|---|---|
| 1. Listing | Name and description | Every session, always |
| 2. Instructions | The SKILL.md body | When the skill is triggered |
| 3. Resources | reference.md, examples, scripts | Only when referenced and needed |
What happens after a skill loads
Once loaded, a skill’s content stays in context across later turns of that conversation. When Claude Code compacts a long session, the docs say it re-attaches the first 5,000 tokens of each recently used skill, within a combined budget of 25,000 tokens. Practical lesson: put your most important rules at the top of SKILL.md, because that is the part that survives compaction.
Why this matters for marketers and writers
A brand voice guide can run to thousands of words. Pasting it into CLAUDE.md means paying for it in every session, even when you are only renaming files. Putting it in a skill, with the long examples in a separate file, means Claude reads the short version only when it is writing copy, and the long version only when it needs an example.
Takeaway: short description, focused SKILL.md, heavy material in side files.
How do Claude Code skills trigger?
Skills trigger two ways. Automatically, when Claude matches your request against a skill’s description. Or manually, when you start your message with /skill-name. Frontmatter settings decide which of those two paths is allowed.
Automatic triggering
Claude reads every skill description at session start. When you type “write three meta descriptions for this landing page”, Claude sees a description that says “Use when the user asks for a meta description” and loads that skill. This is why description wording matters so much. Vague descriptions (“helps with SEO”) fire unpredictably. Specific ones, listing the words people really type, fire reliably.
The paths field narrows this further. A skill with paths: ["content/**/*.md"] only activates automatically when you are working on matching files.
Manual triggering
Type /meta-description at the start of a message. The docs are precise here: the name must come first. Mentioning a skill name after plain text grants permission to run it but does not run it directly. You can pass arguments too, for example /seo-brief best crm for startups, which the skill reads through $ARGUMENTS.
Choosing who can trigger it
| Setting | You can invoke | Claude can invoke | Description always in context |
|---|---|---|---|
| Default | Yes | Yes | Yes |
disable-model-invocation: true | Yes | No | No |
user-invocable: false | No | Yes | Yes |
Use disable-model-invocation: true for anything with side effects. Anthropic’s own example is deployment: “You don’t want Claude deciding to deploy because your code looks ready.” For a marketer, the equivalent is a skill that publishes to your CMS or sends an email. Make those manual.
A safety note on allowed-tools
allowed-tools pre-approves tools for the turn that invokes the skill. The docs warn that workspace trust does not gate this field, so review allowed-tools in any skill you download before running it. A skill from a stranger that pre-approves shell commands deserves a read.
Where do Claude Code skills live?
Personal skills live in ~/.claude/skills/<name>/SKILL.md and work in every project on your machine. Project skills live in .claude/skills/<name>/SKILL.md inside a repository and can be committed so your team shares them. Plugins can also ship skills, which are namespaced as /plugin-name:skill-name.
The full list from Anthropic’s docs:
| Location | Path | Scope |
|---|---|---|
| Enterprise | Managed settings directory | Everyone in the organisation |
| Personal | ~/.claude/skills/<name>/SKILL.md | All your projects |
| Project | .claude/skills/<name>/SKILL.md | This repository |
| Nested | <subdir>/.claude/skills/... | Sessions in that subfolder |
| Added directory | via --add-dir | That session |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled |
When two skills share a name, the docs give the order: enterprise beats personal, and personal beats project. Plugin skills carry a namespace, so they never collide.
Edits are picked up live. Change a SKILL.md and Claude Code sees the new version without a restart.
Installing skills other people wrote
You can copy a folder into one of these paths by hand. Most people use a package command instead. Vercel’s open source skills CLI installs a repo’s skills with:
npx skills add coreyhaines31/marketingskillsAdd --skill copywriting to install one skill from a repo, or --list to see what is inside first. Plugins install through Claude Code’s /plugin command and a marketplace.
how to install Claude Code skills
Skills vs CLAUDE.md, slash commands, subagents, MCP and plugins
CLAUDE.md is always-on memory. Skills are on-demand playbooks. Slash commands are the older, simpler form of skills. Subagents are separate workers with their own context. MCP connects Claude to outside systems. Plugins are the package that bundles any of these for installation.
This is the question Reddit threads ask most, usually as “why would I make a skill when I have CLAUDE.md?” The answer is timing and scope.
| Feature | What it is | Loads when | Best for | Example for a content team |
|---|---|---|---|---|
| Skill | SKILL.md folder with instructions and files | Description always; body on use | Repeatable tasks and workflows | ”Write an SEO brief” playbook |
| CLAUDE.md | Memory file read at session start | Every session, in full | Facts and rules that always apply | ”We write in British English” |
| Slash command | .claude/commands/name.md file | When you type /name | Simple saved prompts | /tweet that reformats a draft |
| Subagent | Separate assistant with its own context window | When delegated a task | Heavy research that would clutter the main chat | Competitor SERP sweep across 10 URLs |
| MCP server | Connector to external tools and data | When its tools are called | Live data: analytics, CMS, search APIs | Pulling Search Console queries |
| Plugin | Installable bundle | When enabled | Sharing a full toolkit | A marketing plugin with skills plus connectors |
Skills vs CLAUDE.md
CLAUDE.md costs context every session. Keep it short: project facts, tone, things that are always true. Anything you only need sometimes, like a 40-point audit checklist, belongs in a skill. Several community guides call an overstuffed CLAUDE.md an anti-pattern for exactly this reason.
Skills vs slash commands
Anthropic’s docs describe skills as the superset. Files in .claude/commands/ still work and still create /name commands. Skills add a folder for supporting files, control over who can invoke them, and automatic loading. If a skill and a command share a name, the skill wins. For anything new, write a skill.
Skills vs subagents
They combine rather than compete. A skill with context: fork runs its instructions inside a subagent, which does not see your conversation history, so the instructions must stand alone. Going the other way, a subagent can preload skills as reference material through a skills field.
Skills vs MCP
A skill teaches Claude how to do something. MCP gives Claude access to something. An SEO audit skill can tell Claude which checks to run; an MCP server for your rank tracker supplies the data. Many good workflows use both.
Skills vs plugins
A plugin is packaging. It can contain skills, commands, subagents, hooks and MCP configuration, installed as one unit. Anthropic’s knowledge-work-plugins repo shows the shape: each plugin folder holds a manifest, connector config, commands and skills.
Where to find Claude Code skills (free and paid)
Most quality skills are free and open source on GitHub. Start with Anthropic’s official repos, then the large community collections, then directories that index them. Paid packs exist, but you can usually inspect free alternatives first.
Star counts below were read from the GitHub API on 1 November 2026. They move daily.
GitHub repositories
| Repo | What it covers | Stars | Cost |
|---|---|---|---|
| anthropics/skills | Anthropic’s example and document skills | ~186,000 | Free |
| anthropics/claude-plugins-official | Anthropic’s official plugin directory | ~45,700 | Free |
| anthropics/knowledge-work-plugins | Role plugins, including Marketing | ~34,300 | Free (Apache-2.0) |
| ComposioHQ/awesome-claude-skills | Curated list of community skills | ~78,500 | Free |
| coreyhaines31/marketingskills | CRO, copywriting, SEO, growth skills | ~57,800 | Free (MIT) |
| alirezarezvani/claude-skills | Large multi-domain set incl. marketing | ~29,100 | Free (MIT) |
| AgriciDaniel/claude-seo | Technical and on-page SEO skills | ~25,400 | Free (MIT) |
| TheCraigHewitt/seomachine | SEO content workflow for Claude Code | ~7,600 | Free (MIT) |
| AgriciDaniel/claude-blog | Blog writing and optimisation skills | ~2,600 | Free (MIT) |
The Marketing plugin in knowledge-work-plugins is described in its README as covering content drafting, campaign planning, brand voice, competitor briefs and performance reporting, with connectors such as HubSpot, Ahrefs, Canva and Notion.
Directories and marketplaces
| Directory | What it is | Cost |
|---|---|---|
| skills.sh | Vercel’s Agent Skills directory and leaderboard | Free |
| claudemarketplaces.com | Independent index of skills, MCP servers and plugin marketplaces; says it is not affiliated with Anthropic | Free |
| claude.com/plugins | Anthropic’s plugin listing | Free to browse; plugins need a Claude plan |
Paid packs
| Pack | What it claims | Price |
|---|---|---|
| SuperSkills | Bundle of 139 skills incl. marketing, CRO, SEO | $50 one-time (per its own page) |
We found several other paid bundles while researching, many using countdown timers and “slots left” urgency, and some that do not show the skill files before purchase. We have left them out. Before paying for any pack, ask to see a sample SKILL.md, and compare it with the free repos above. Skills are plain text, so quality is easy to judge once you can read them.
best Claude Code skills for marketers Claude Code skills for SEO
Who should use skills (and when not to bother)
Skills pay off when you repeat a task with stable rules: briefs, audits, rewrites, reports. They are not worth it for one-off questions, or for rules so short they fit comfortably in CLAUDE.md.
Good fits
- SEO people: keyword clustering steps, on-page audit checklists, schema templates. skills for SEO audits and keyword research skills
- Writers: house style, banned words, FAQ formats, humanising passes. skills for content writers
- Copywriters: headline formulas, offer frameworks, landing page structures. skills for copywriters
- Non-developers: you do not need to code. A SKILL.md is a text file. Claude Code skills for non-developers
Poor fits
- A one-sentence rule. Put it in CLAUDE.md.
- Anything needing live data with no connector. Add an MCP server first.
- A task you have done once. Write the skill after the third repeat, when you know what “good” looks like.
Common mistakes
- Vague descriptions. “Marketing helper” will not trigger reliably. Name the requests.
- Giant SKILL.md files. Over 500 lines, move material to reference files.
- Broken YAML. A stray colon can wipe the frontmatter silently.
- Auto-triggered side effects. Publishing or sending should be manual.
- Unreviewed downloads. Read
allowed-toolsand any scripts before running.
FAQ
What are Claude Code skills in simple terms?
Saved playbooks. Each is a folder with a SKILL.md file that tells Claude when to use it and what steps to follow.
What is the difference between skills and CLAUDE.md?
CLAUDE.md loads in full every session. Skills load only their short description until a task needs them, so they suit longer, situational instructions.
Are skills the same as slash commands?
Skills are the superset. Old .claude/commands/ files still work, but skills add supporting files, automatic loading and invocation control.
Where do I put Claude Code skills?
~/.claude/skills/<name>/SKILL.md for all your projects, or .claude/skills/<name>/SKILL.md inside one repository.
How does Claude decide to use a skill?
It compares your request with each skill’s description. A close match loads the skill.
Why is my skill not triggering?
Usually the description is too vague, or the YAML frontmatter failed to parse. Check that --- starts on line one.
Can I stop Claude from running a skill automatically?
Yes. Set disable-model-invocation: true and it only runs when you type /name.
Do skills use up my context window?
Only lightly. Descriptions are always present; full content loads on use.
Do I need to know how to code to write a skill?
No. A basic skill is a Markdown file with plain instructions.
What is the difference between skills and MCP?
Skills give instructions. MCP servers give access to external tools and data. They work well together.
What is the difference between skills and subagents?
A subagent is a separate worker with its own context. A skill can run inside one using context: fork.
What is a plugin in Claude Code?
An installable bundle that can include skills, commands, subagents, hooks and MCP settings.
How do I install skills from GitHub?
Run npx skills add owner/repo, or copy the skill folder into your skills directory.
Do Claude skills work outside Claude Code?
The format follows the open Agent Skills standard, and community posts report the same skills working in Claude.ai and the API. Claude Code-only extensions will not carry over.
Are Claude Code skills safe?
They can run tools and scripts. Review allowed-tools and any bundled scripts before using a skill from someone you do not know.
Are paid skill packs worth it?
Sometimes, but large free repos cover most marketing and SEO tasks. Inspect sample files before paying.
Sources and method
- Anthropic, Claude Code skills documentation: https://code.claude.com/docs/en/skills (structure, fields, locations, precedence, triggering, compaction budgets).
- Anthropic, knowledge-work-plugins README: https://github.com/anthropics/knowledge-work-plugins
- Vercel skills CLI: https://github.com/vercel-labs/skills and https://skills.sh
- GitHub API star counts, read 1 November 2026.
- Community questions from Reddit threads on r/ClaudeAI and r/ClaudeCode, used for FAQ selection only.
Your next step
Pick one task you repeated three times last week. Write its steps as a numbered list, add a two-line frontmatter with a specific description, and save it as ~/.claude/skills/<task>/SKILL.md. Then ask Claude to do the task without mentioning the skill and see if it fires.
