How to Use Claude Code Skills (Install, Run, Manage)

Most tutorials on Claude Code skills stop at install and declare victory. The parts that cost you time come after. The docs go quiet exactly there. This page covers the whole loop the way I run it, because the team that wrote it runs on skills.

To use a Claude Code skill, install it first. Copy its folder into ~/.claude/skills/ for personal use, or into .claude/skills/ for a project. Claude Code reads the SKILL.md description and loads the skill when your request matches. You can also run it directly with /skill-name. Verify with What skills are available?

TL;DR

• Install: copy the skill folder into ~/.claude/skills/ or .claude/skills/.
• Load: Claude Code matches your request against each skill’s description.
• Run: type /skill-name to skip the matching and run now.
• Fix: claude --debug prints the parse error, and the off switches live in skillOverrides.

How do I install a Claude Code skill I found on GitHub?

Find the folder that holds the SKILL.md file. Copy or clone it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. Start a fresh session, then type What skills are available? to confirm it shows up.

That’s the whole Claude Code skills tutorial for installs, minus one step: read the skill before you run it. GitHub hosts public skill collections, like Corey Haines’ marketing skills. Most installs come down to a clone and a copy.

A skill is just a folder. The SKILL.md file inside it does the work. Both install paths come from the skill folders section of the Claude Code skills documentation. The CLI reads them at the start of every session.

Some skills ship inside plugins. A plugin bundles its skills with its commands, so the bundled skills listing includes them once the plugin loads.

I read the whole skill file first. A bad one wastes real hours, and the field is young. Anyone selling a decade of agent experience is selling you something. New skills get tested on a scratch project before they touch work I care about.

	Personal skill	Project skill
Where it lives	~/.claude/skills/	.claude/skills/ in the project
Who can use it	Only you, on this machine	Anyone who clones the repo
What it’s for	Workflows you use everywhere	Steps tied to one codebase
When it disappears	If you switch machines	If it’s never committed

Read a downloaded skill before the first run. The file is the contract, and the trust has to be earned.

How does Claude Code decide when to use a skill?

Claude Code reads the name and description in each SKILL.md and loads a skill when your request matches the description. The description is the trigger. A vague one means the right skill stays quiet, no matter how good the steps are.

Only the name and description sit in the listing, and the full body loads after a match. The Claude Code skills documentation shows that split in its invocation table.

Anthropic’s team runs hundreds of skills in active use. Their post on building with skills names three patterns that repeat:

• Gotchas sections that say what to avoid.
• Progressive disclosure, so detail loads only when asked.
• Descriptions written for the trigger, not the reader.

Claude Code skills follow the Agent Skills open standard, which the docs say works across multiple AI tools. Outside Claude Code, only the frontmatter fields the spec defines transfer.

CLAUDE.md holds project memory. Skills hold repeatable procedure.

My outreach pipeline takes in roughly 200 form submissions a day. The follow-up skill fires the same way. Its description names the trigger, and every new lead matches it. That’s the whole mechanism.

Write the trigger into the description. The skill then runs itself.

How do I run a skill myself instead of waiting for it to load?

Type a slash, the skill’s name, and it runs right away: /skill-name. Direct invocation skips the description matching, so it works even when auto-load would miss. Open /skills to see the list and pick one.

The skills docs cover both paths side by side. Automatic loading matches the description. A direct /skill-name call skips straight to the run. Slash commands are the same mechanism behind /skills and the built-ins like /doctor.

The same path covers Claude Code custom skills you wrote yourself. The name is all you need.

I built the pipeline that wrote this post, and it calls each agent by skill name. Direct invocation is deterministic and repeatable. A description match is a guess, and guesses fail exactly when you’re in a hurry.

When you know the skill you need, name it. A direct /skill-name call never waits on a match.

How do I use a skill that calls a script or a tool like MCP?

A skill gets tools the same way you do. An MCP server exposes tools under full names like mcp__server__tool, and scripts only run once you list them in allowed-tools. Nothing a skill runs starts without a grant you made.

MCP stands for the Model Context Protocol. It is how Claude Code reaches external tools. The MCP documentation shows the addressing, server first: mcp__github__list_prs or mcp__jira__create_issue. That full name is what goes in a skill’s allowed-tools list and in permission rules.

For Claude Code skills examples, the docs’ deploy example is the one to copy. It sets context: fork and disable-model-invocation: true together. The fork starts with no conversation history, a detail the subagents documentation spells out. The main conversation stays light.

Hooks are the enforcement layer. A PreToolUse hook can block a tool call before it runs, and the skills documentation covers hooks alongside permissions.

Figuring out which layer does what is half the setup. The comparison of skills vs MCP vs agents maps the split.

A skill runs only what you approve. Tools and scripts each need their own grant.

How do I keep my skill list from eating the conversation?

The skill list pays rent in context. The default budget is 1% of your context window, and every skill you add makes the listing longer. /skill-doctor shows what each skill costs and how often you use it.

The budget scales at 1% of the model’s context window, and a full listing eats that on every turn. When the listing overflows, the least-used descriptions drop first. The skill listing budget section of the skills documentation spells out the dials. skillListingBudgetFraction and SLASH_COMMAND_TOOL_CHAR_BUDGET change the cap, and each entry’s text is capped at 1,536 characters.

Two switches keep the list lean. Set disable-model-invocation: true in the frontmatter, or put user-invocable-only in skillOverrides when you don’t want to edit the file. name-only is the softer option. The name stays listed, and the description stops triggering auto-load. The skillOverrides entry in the skills documentation lists all four states.

Every skill you add spends context before it earns any back.

Why is my skill not loading and how do I fix it?

Run claude --debug and the parse error prints where the skill broke. claude plugin validate finds SKILL.md files with broken frontmatter, and /skill-doctor flags the skills nothing uses. Most failures are a broken SKILL.md or a description that never matches.

Malformed YAML is the quiet killer. The skill loads with empty metadata, so it looks fine and never matches. claude --debug prints the parse error. The skills documentation adds claude plugin validate for finding SKILL.md files whose frontmatter doesn’t parse, and it needs Claude Code v2.1.233 or later.

I check in the same order the documentation does. The description comes first, then the file itself. For how to write Claude Code skills from scratch, the walkthrough on how to create Claude Code skills goes line by line. This section is the other half.

Symptom	Likely cause	Fix
Skill never shows in the list	Wrong folder, or a stale session	Check the path, start a fresh session
Listed but never fires	Malformed YAML loads empty metadata	claude --debug prints the error
Loads but does the wrong thing	Description matches the wrong request	Make it specific, or call /skill-name
Runs wrong steps	allowed-tools or script paths are off	Read the body, fix the paths

Debug the file first. Claude Code is usually telling the truth.

For a managed version, see the skills bundle.

FAQ

What is the SKILL.md format, and do I have to write one before I can use a skill?

SKILL.md is a plain text file. YAML frontmatter at the top carries the name and the description, and the instructions below are markdown. Every skill needs one, because the description decides when it loads. You don’t write one to use a skill. You write one to make it.

The SKILL.md reference in the skills documentation starts with the name and the description in the frontmatter. Writing the file is separate. The walkthrough on how to create Claude Code skills covers it line by line.

Where are Claude Code skills stored on disk?

Three places. Personal skills live in ~/.claude/skills/ and follow you between projects. Project skills live in .claude/skills/ and travel with the repo. Skills that arrive with a plugin live inside the plugin directory.

Do skills work with Claude Code subagents?

Yes. Set context: fork in the skill and it runs as its own subagent with a fresh context. The skill keeps its files and its tools, and the fork isolates the run from your main conversation.

Can I use a skill that came from claude.ai in Claude Code?

Yes. Skills you build on claude.ai sync through the Claude desktop app, and Claude Code loads them like personal skills. If you skip the desktop app, export the skill folder and copy it into ~/.claude/skills/.

The synced skills section of the skills documentation covers where they land and what happens on a name clash.

How do I turn a skill off without deleting it?

Two switches. Set disable-model-invocation: true in the frontmatter and the model never auto-loads it, though /skill-name still works. Or put user-invocable-only in skillOverrides to get the same result without editing the file.

Boring work should run itself. Skills run the dull parts of my week, and this post came out of a team of them. The skills bundle holds the instructions I actually run, like Skill Creator and the Anti-Slop Humanizer. Skill Creator writes new skills in a consistent format, and the Anti-Slop Humanizer is the last pass on every page, this one included.

AutomateReal skills

If you want help finding the first workflow worth automating, a discovery call maps it. It takes about 30 minutes.

AutomateReal services