Claude Code skills guide: SKILL.md format, where skills live, invocation control, and troubleshooting
A Claude Code skill is a folder with a SKILL.md file that Claude loads when relevant or you run as a slash command. Learn the format, personal vs project locations, key frontmatter fields, invocation control, context cost, and fixes.
A Claude Code skill is a folder with a SKILL.md file: you write down the instructions, checklist, or multi-step procedure you keep pasting into chat, and Claude loads it automatically when it is relevant, or you invoke it directly with /skill-name. Personal skills live in ~/.claude/skills/your-skill/SKILL.md, and project skills live in the repository at .claude/skills/your-skill/SKILL.md. This guide follows Anthropic's official Claude Code documentation to cover how to write a skill, where to put it, how to control who invokes it, and how to troubleshoot it, so you can decide whether an instruction belongs in a skill or in CLAUDE.md.
When something should become a skill
The docs give a concrete test. Create a skill when you keep pasting the same instructions, checklist, or procedure into chat, or when a section of CLAUDE.md has grown from a fact into a procedure. The difference is loading. CLAUDE.md content sits in context every session, while a skill's body loads only when it is used, so long reference material costs almost nothing until you need it.
Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same, and existing command files keep working. Skills add a directory for supporting files, frontmatter to control who invokes them, and automatic loading when relevant, so the docs recommend skills for new work.
Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools. Claude Code adds extensions on top, including invocation control, running in a subagent, and dynamic context injection.
Your first skill in three steps
The official example summarizes uncommitted changes and flags risks. First, create the folder in your personal skills directory: mkdir -p ~/.claude/skills/summarize-changes. Personal skills are available in all your projects on that machine.
Second, write SKILL.md. Every skill has YAML frontmatter between --- markers, which tells Claude when to use it, followed by markdown instructions Claude follows when the skill runs. The folder name, or the frontmatter name, becomes the command, and the description helps Claude decide when to load it. The example body contains the line ` !git diff HEAD `. That is dynamic context injection: Claude Code runs the command and replaces the line with its output before Claude reads the skill, so the current diff is already inlined.
Third, test it. Edit a file in a git project, run claude, and either ask something that matches the description, such as "What did I change?", or type . Both should return a short summary and a list of risks.
