How to write and use Skills in Claude Code

Who this is for and what you will be able to do

This guide is for anyone who keeps pasting the same instructions, checklist, or multi-step procedure into Claude Code. When you finish, you will be able to write a first skill, save it in the right folder, and understand how its description decides when Claude loads it. You will also know which frontmatter fields change its behavior.^[1]

What a skill is and how it differs from CLAUDE.md

A skill is a SKILL.md file that contains instructions. Claude uses it when it is relevant, and you can invoke it directly with /skill-name.^[1]

Write a skill when you find yourself pasting the same instructions, checklist, or multi-step procedure into chat. Another sign is a section of CLAUDE.md that has grown from facts into a procedure.^[1]

The main difference is when the content loads. Contents of CLAUDE.md are always loaded. The body of a skill loads only when the skill is used, so long reference material costs almost nothing until it is needed.^[1]

Claude Code skills follow the Agent Skills open standard. Claude Code extends that standard with invocation control, subagent execution, and dynamic context injection.^[1]

Preparation

You need Claude Code installed and a folder for your skills. A skill is just a folder with a Markdown file, so no extra tool is required. The claude plugin validate command, which checks skill frontmatter, requires Claude Code v2.1.233 or later.^[1]

Write your first skill

1. Create the skill directory. A personal skill goes in ~/.claude/skills/<skill-name>/. It is available in every project on that machine, and you can create the folder with a command such as mkdir -p ~/.claude/skills/summarize-changes.^[1]
2. Write SKILL.md in that directory. It has two parts: YAML frontmatter between --- markers that tells Claude when to use the skill, and a Markdown body with the instructions Claude follows when the skill runs.^[1]
3. The directory name, or the name field in the frontmatter when you set one, becomes the command you type. The description helps Claude decide when to load the skill on its own.^[1]

The following example is a skill that you invoke by hand, and that lets Claude run only three git commands without asking:

``yaml --- name: commit description: Stage and commit the current changes disable-model-invocation: true allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *) --- ``^[1]

Only description is recommended in the frontmatter; every other field is optional. Put the most important use case first in description. The combined description and when_to_use text is cut off at 1,536 characters in the skill listing.^[1]

If Claude does not use a skill when you expect it to, check three things. First, make sure the description includes the words users would naturally say. Second, ask what skills are available and confirm the skill appears. Third, invoke it directly with /skill-name if it is user-invocable. If the YAML does not parse, Claude Code loads the body with empty metadata. Run Claude Code with --debug to see the parse error.^[1]

Where to save a skill

The location decides which sessions load it.^[1]

• Enterprise skills sit in the .claude/skills/ folder inside the managed settings directory. They reach all users on machines where the organization deploys them.^[1]
• Personal skills go in ~/.claude/skills/<skill-name>/SKILL.md. They work in all your projects on that machine, but not in Cowork or cloud sessions.^[1]
• Project skills go in .claude/skills/<skill-name>/SKILL.md inside the repository. Commit them so the team gets them too.^[1]
• Plugin skills sit at <plugin>/skills/<skill-name>/SKILL.md. Wherever the plugin is enabled, they run as /plugin-name:skill-name.^[1]

Project skills are searched broadly. Claude Code loads them from the directory where you start, and from every parent directory up to the repository root. Starting in packages/frontend/ still picks up skills defined at the root.^[1]

Skills in a .claude/skills/ subdirectory below the starting point do not load at startup. They load the first time Claude reads or edits a file in that subdirectory, and they stay available for the rest of the session.^[1]

Directories added with --add-dir contribute the skills in their .claude/skills/ folder for that session.^[1]

Do not name a skill folder synced, in any capitalization. Claude Code stores skills downloaded from claude.ai in ~/.claude/skills/synced/.^[1]

Do you need to restart after editing?

No. Claude Code watches skill directories. Adding, editing, or removing a skill under ~/.claude/skills/ or the project .claude/skills/ takes effect within the current session. The exception is a top-level skills directory that did not exist when the session started. For that one, run /reload-skills, and run it again after each later change in that directory.^[1]

Invocation control and tool approval

By default you and Claude can both invoke any skill. Two frontmatter fields restrict this.^[1]

• disable-model-invocation: true stops Claude from loading the skill on its own. Use it for workflows with side effects, such as deployments, or for anything whose timing you want to control. The default is false.^[1]
• user-invocable: false hides the skill from the / menu, so only Claude can invoke it. Use it for background knowledge. The default is true.^[1]

The allowed-tools field lets Claude use the listed tools without asking during the turn that invokes the skill. The grant clears when you send your next message, so invoke the skill again to re-apply it.^[1]

Project skills apply their allowed-tools even in a folder you have not trusted. Review the allowed-tools of any skill that comes from a repository before you run Claude Code there.^[1]

Arguments, subagents, and supporting files

Anything typed after the skill name replaces the $ARGUMENTS placeholder. $ARGUMENTS[N] or $N selects an argument by its 0-based index.^[1]

${CLAUDE_SKILL_DIR} expands to the directory that contains SKILL.md. Use it to reference scripts bundled with the skill, so the path does not depend on the current working directory.^[1]

Adding context: fork runs the skill in a new subagent. The subagent type comes from the agent field. The subagent does not see your conversation history, so the instructions must stand on their own. If the task depends on the earlier discussion, do not use this setting.^[1]

Supporting files such as reference.md, examples.md, and scripts/helper.py can sit beside SKILL.md. Mention in SKILL.md what each file contains and when to read it. Claude loads reference files when they are needed, and it runs scripts instead of loading them.^[1]

Common problems

If Claude stops following a skill partway through a session, remember that the skill content stays in the conversation but Claude Code does not re-read the file on later turns. After compaction, Claude Code keeps only the first 5,000 tokens of each invoked skill, so put the most important instructions near the top.^[1]

A rule that must hold every time belongs in a hook, not in a skill. A hook runs whenever its event occurs, whether or not Claude is following a skill.^[1]

Next steps

For every frontmatter field, the string substitution variables, and the full invocation rules, read the Skills page in Claude Code's official documentation.^[1]