How to Create Claude Code Skills (Step-by-Step Guide)

Create a Claude Code skill by adding a folder with a SKILL.md file to ~/.claude/skills/ or your project’s .claude/skills/. The file holds YAML frontmatter with the skill’s name and description, plus markdown instructions. Claude Code finds skills from their description and loads them when the task matches, no config file needed.

Most advice on Claude Code skills is theory from people who have never built one. I run a local SEO agency, and this is the plain version: a folder, a file, and the frontmatter that makes it work. Everything I automate started as a procedure nobody wanted to do twice, and a skill is that procedure with a trigger attached.

TL;DR

• A Claude Code skill is a folder with a SKILL.md file: YAML frontmatter that names and describes it, plus markdown instructions.
• Personal skills go in ~/.claude/skills/, project skills in .claude/skills/. Claude Code matches by description and loads the skill when the task fits.
• No config file, no registry. To install, copy the folder. To update, edit the file. To remove, delete the folder.
• The file follows Anthropic’s Agent Skills standard, so the same skill works in other tools that adopt it.

What are Claude Code skills and how do they work?

A Claude Code skill is a folder with a SKILL.md file. The file carries YAML frontmatter with the skill’s name and description, plus markdown instructions. Claude Code matches your request against the description and loads the skill when it fits.

Claude Code loads a compact listing of skill names and descriptions into context so it knows what exists. Full skill content loads only when the skill is invoked, and it stays in context across turns, so every line you write is a recurring token cost. That is why the SKILL.md format stays short and specific. The format works the same way in the Claude Agent SDK, which reads the same .claude/skills/<name>/SKILL.md layout.

For an operator, a skill is the smallest hiring decision in the stack. Hiring a first AI employee to hire is a bigger commitment with a bigger workflow. A skill is the single task you hand it. It does not interview. It does exactly what the file says. When I automate a task, I want the boring version repeated exactly, and a skill is the most literal way to write that version down.

How are Claude Code skills different from subagents, commands, and hooks?

A skill adds instructions to your context. A subagent runs as a separate fork with no conversation history. A command is a slash shortcut you invoke by name. A hook fires on an event. A skill is the only one Claude Code loads for you.

	Skill	Subagent	Command	Hook
What it is	Instructions added to your context	A separate agent run	A slash shortcut	A script on an event
Who starts it	Claude Code or you	You or a skill	You	An event in the session
Conversation	Shares your context	Own context, no history	Shares your context	None

The boundaries matter in practice. The skills vs subagents question is the one I hear first, and the split is simpler than it looks. A skill adds knowledge and steps to the conversation you are already in. A subagent runs elsewhere and reports back, which suits long jobs like a full code review. A command is a file you invoke by name, and the two formats have merged: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy, and when both exist, the skill wins. Hooks fire scripts on events, like before a tool runs or when a session starts.

Skills did not replace the other three. They are the layer that decides itself. You can also force a skill to run as its own subagent with context: fork in its frontmatter. The forked skill has no access to your conversation history, runs in the background by default, and drops its result into the conversation when done.

How do you create a Claude Code skill, step by step?

Make a folder under ~/.claude/skills/ for personal use or .claude/skills/ for a project. Add a SKILL.md file with YAML frontmatter that names the skill and describes it, then write the instructions in markdown. Test it with a real request. No config file required.

This tutorial keeps to the plain path: one folder, one file, one test.

1. Pick the level. Personal skills in ~/.claude/skills/ apply to all your projects. Project skills in .claude/skills/ apply to one repository. The docs call these the skill folders, and the choice is the first decision you make.
2. Create the folder.

mkdir -p ~/.claude/skills/summarize-changes

3. Write SKILL.md. Frontmatter between — markers first, markdown instructions after.

---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

!`git diff HEAD`

Summarize the changes in two or three bullet points, then list risks such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

The !git diff HEAD line is dynamic context injection. Claude Code runs the command and replaces the line with its output before the skill is read, so the instructions arrive with the current diff already inlined.

4. Test it. Ask “What did I change?” and let Claude match the description, or type /summarize-changes to invoke it directly. Test in a fresh session, because leftover context from writing the skill masks gaps in the instructions.
5. Commit the folder so the skill survives the machine it was born on. I commit with the description as the message, because a description that cannot stand alone in a commit is not ready to ship.

My outreach system pulls in roughly 200 form submissions a day. Automating the follow-up is what turned that from a weekend job into a running system, and a skill is the smallest unit of that kind of automation. I run a local SEO agency, and the automation that changed my week was putting follow-up on autopilot. Every skill I ship started as one of those repeatable steps.

What is the SKILL.md format and its frontmatter?

SKILL.md is markdown with YAML frontmatter at the top. The one field that matters is the description: it makes discovery work, so Claude Code knows when to load the skill. The name is optional and defaults to the directory name. The body holds the step-by-step instructions. If you leave the description out, Claude Code falls back to the first paragraph of the body.

The full template is frontmatter plus body. Save this template once, and every claude code skills template you write after starts from the same base.

---
name: weekly-report
description: Draft the weekly status report from the project files. Use when the user asks for a weekly report, a status update, or a summary of what changed.
allowed-tools: Read Grep
---

Write a weekly report with three sections: what shipped, what is blocked, what is next. Name the files and numbers you based the report on.

Only the description is recommended. Every other SKILL.md format field is optional. If you omit the description, Claude Code uses the first paragraph of the body. The combined description and when_to_use text is truncated at 1,536 characters in the skill listing, so the key use case goes first. The name defaults to the directory name in listings, and the directory name is where the /command comes from.

Claude Code accepts every field in its frontmatter reference: when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, allowed-tools, disallowed-tools, model, effort, context, agent, background, hooks, paths, shell, plus the spec fields below. Outside Claude Code the picture is stricter. Per the skills documentation, the Agent Skills spec allows six frontmatter fields: name, description, license, compatibility, metadata, and allowed-tools. When you upload a skill to claude.ai, call the Skills API, or package with package_skill.py, any extra field fails with a hard error instead of a warning.

The fields that matter for real work: allowed-tools pre-approves tools for the turn that invokes the skill, disable-model-invocation stops Claude from loading a skill on its own, and context: fork runs it as a subagent. The field I check first when I review a skill is the description. A description that reads like an ad gets skipped. One that reads like a request gets used.

What do good Claude Code skill examples look like?

A good skill does one job. Its description reads like the request you would type. Its instructions name the files, tools, and output format so the model never guesses. Keep it short, because the content stays in context and every line costs tokens.

The docs ship a working example: a summarize-changes skill that pulls the live diff with dynamic context injection, so the response is grounded in the actual working tree. Another pattern is a skill that bundles a script. Claude Code skills can bundle and run scripts in any language, and the docs show a codebase-visualizer that calls python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py, with the path written so it resolves whether the skill is installed at the personal, project, or plugin level.

The best claude code skills examples to study come free with Claude Code. Bundled skills like /code-review, /debug, and /batch ship in every session. Reading them shows the format at production quality, and they are the closest thing to a style guide the format has.

Then there is the version I actually ship. I built the AI SEO team writing this post, and the pipeline works because every stage is a written procedure with a trigger. That is what a SKILL.md is: a procedure with a trigger. The skills bundle at automatereal.com ships 19 ready-made Claude Code skills, each one a skill file with the method inside it. Two of the 19 are named Skill Creator and Skill Runtime Builder. Skill Creator turns any workflow you describe into a clean, working skill file. Skill Runtime Builder hardens a skill so a cheaper or unattended model runs it safely.

Anyone selling a decade of agent experience is selling you something. The people who know this format best are the ones using it weekly, not lecturing about it. If you are still deciding whether the whole agent idea fits your shop, the AI agents for small business post makes the case. This one is the how.

Where do Claude Code skills live on disk and how does Claude Code discover them?

Personal skills live in ~/.claude/skills/. Project skills live in .claude/skills/ at the repository root. Plugins ship their own skills folder, and enterprise skills come from managed settings. Claude Code watches all four and matches by name and description.

Location	Path	Applies to
Enterprise	managed settings	everyone in your organization
Personal	~/.claude/skills/<skill-name>/SKILL.md	all your projects
Project	.claude/skills/<skill-name>/SKILL.md	this repository only
Plugin	<plugin>/skills/<skill-name>/SKILL.md	wherever the plugin is enabled

Discovery follows the skill folders rules. When names collide, enterprise overrides personal, personal overrides project, and any level overrides a bundled skill. A skill and a command with the same name resolve in favor of the skill. Project skills load from your start directory and every parent up to the repository root. Nested .claude/skills/ folders load the first time Claude Code reads or edits a file inside that subdirectory, which is how a monorepo package ships its own skills.

The claude code skills list for your machine is the /skills menu. I check it before I trust that a skill exists, because a skill that is not listed cannot be loaded. Claude Code watches skill directories live, so edits show up in the current session without a restart. One exception: a skills directory created after the session started needs a restart before it is watched. Deleting the folder removes the skill.

How do you install and share Claude Code skills?

Install a skill by copying its folder into ~/.claude/skills/ or .claude/skills/. Share it by committing the folder to version control, shipping it in a plugin, or deploying it through managed settings. The same SKILL.md works in other Agent Skills tools.

The docs define three distribution scopes. Project skills are committed to version control, so a team clones the repo and gets the skills with it. Plugins ship a skills/ directory and distribute with the plugin. Managed settings deploy skills to every machine in an organization. GitHub is where most claude code skills are published, and installing one is a clone plus a copy into the right folder.

For packaging, Anthropic ships package_skill.py with the anthropics/skills repository. Because the format follows the Agent Skills standard, a skill you write for Claude Code also works in Claude Agent SDK sessions without a rewrite. The SDK reads the same folder layout, checks the description, and matches it the same way.

I build a free website for a prospect before they pay. Proof first, payment later. Skills deserve the same treatment: run one on a throwaway task before you trust it with work that has a deadline. The skills I sell and the skills I work with follow the same rule, and it has never sent me backwards.

For a managed version, see the skills bundle.

Related: what are claude code skills

FAQ

How do I debug a skill that is not being picked up?

Run /skills to see whether Claude Code loaded it at all. Check the folder location and the YAML frontmatter, and make the description match the words you actually type. If you created the folder after the session started, restart Claude Code. Then test again.

The skill files I review most often fail the same way: the description is written for the author, not for the request. Malformed YAML is easier to catch, because /name still works but there is nothing to match, and running with –debug prints the parse error. If the description is vague, Claude Code sees the skill and never triggers it. The skill folders docs also recommend a baseline comparison for behavior: run realistic prompts with the skill available and disabled, and compare the outputs. Fresh sessions only, because leftover context hides gaps. The skill-creator plugin automates that loop.

Can a Claude Code skill call scripts or MCP tools?

Yes. A skill can run bundled scripts and call MCP tools by their full name, such as mcp__server__tool. The allowed-tools field pre-approves tools for the turn that invokes the skill, and the grant clears when you send your next message.

The MCP docs are explicit: reference a tool by its full name in permission rules and in a skill’s allowed-tools list. The full form is mcp__server-name__tool-name, and the shorter server key alone does not match. Scripts work the same way, in any language. The docs show a codebase-visualizer skill that bundles a Python script and pre-approves it with allowed-tools: Bash(python3 *).

Should I build custom Claude Code skills or start with existing ones?

Start with something working, then make it yours. A custom skill pays off when the workflow is yours and repeats every week. For a generic task, an existing skill gets you running today and shows you the format by example.

The skills bundle ships 19 ready-made skill files covering the common jobs, and reading their SKILL.md files is the fastest way to learn the format from working examples. I read a few of them before I wrote my own, and the format clicked in one sitting. Build custom when the workflow is specific enough that no off-the-shelf file matches it. That threshold hits sooner than you expect.

How do I update or remove a skill?

Edit the SKILL.md file to update a skill, and Claude Code picks the change up in the current session. Remove a skill by deleting its folder. There is no registry to clean and no config file to edit.

Skills synced from claude.ai are the exception: turn them off on your account and the next sync removes the local copy. To keep a skill installed but stop Claude Code from loading it on its own, set disable-model-invocation: true in its frontmatter. The skill stays listed, and only you can invoke it.

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