[{"data":1,"prerenderedAt":53},["ShallowReactive",2],{"blog-claude-code-skills":3,"blog-related-claude-code-skills":36},{"slug":4,"title":5,"description":6,"category":7,"categoryId":8,"keyword":9,"date":10,"minutes":11,"body":12,"html":13,"headings":14},"claude-code-skills","Claude Code skills: what they are and how to write one","A Claude Code skill is a folder with a SKILL.md that Claude loads when relevant or you call with a slash. See the format, frontmatter fields and an example.","Getting started","getting-started","claude code skills","2026-11-17",5,"A Claude Code skill is a folder containing a `SKILL.md` file: Markdown instructions with a short YAML header. Claude loads it when your request matches its description, or you run it yourself with `\u002Fskill-name`. Skills are where procedures live (how to cut a release, how to add a migration), so they do not take up room in your CLAUDE.md on every session.\n\n## What is a skill, and why not just use CLAUDE.md?\n\nBoth give Claude instructions, but they load differently. [CLAUDE.md](\u002Fblog\u002Fclaude-md-guide) is read at the start of every session, so it should hold short facts that are always true: commands, layout, conventions. A skill's description is always visible to Claude, but its full content only loads when it is invoked. That makes skills the right home for long, task-specific procedures.\n\nA good test: if you would write \"when I ask to X, do steps 1 to 6\", it is a skill. If it is \"we use pnpm\", it is CLAUDE.md.\n\nSkills live in these places:\n\n| Scope | Path |\n| --- | --- |\n| Personal, all your projects | `~\u002F.claude\u002Fskills\u002F\u003Cname>\u002FSKILL.md` |\n| Project, shared via git | `.claude\u002Fskills\u002F\u003Cname>\u002FSKILL.md` |\n| A subdirectory | `\u003Csubdir>\u002F.claude\u002Fskills\u002F\u003Cname>\u002FSKILL.md` |\n| Plugin | `\u003Cplugin>\u002Fskills\u002F\u003Cname>\u002FSKILL.md`, used as `\u002Fplugin-name:skill-name` |\n| Organization | in the managed settings directory |\n\nIf a name exists in several scopes, enterprise beats personal, and personal beats project. Claude Code picks up added, edited or removed skills within the current session, with one exception: if you create a top-level skills directory that did not exist when the session started, run `\u002Freload-skills`.\n\n## How do you write a SKILL.md?\n\nA minimal skill is a directory with one file. This one summarizes your uncommitted work:\n\n```md\n---\nname: summarize-changes\ndescription: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.\n---\n\n## Current changes\n\n!`git diff HEAD`\n\nSummarize the changes in two or three bullets, then list any risks:\nmissing tests, changed public APIs, leftover debug code.\n```\n\nThe line starting with `` !` `` runs the shell command before Claude sees the skill and substitutes its output, so the diff is already in the prompt. A failed command aborts the invocation. For multi-line commands, use a fenced block opened with ` ```! `. If you would rather block this feature, set `\"disableSkillShellExecution\": true` in settings.\n\n## What frontmatter fields matter?\n\nThe frontmatter must start on the file's first line. Field names must match exactly; unknown fields are ignored without an error. The ones you will actually use:\n\n| Field | What it does |\n| --- | --- |\n| `name` | The name in the `\u002F` menu. Defaults to the directory name. |\n| `description` | What the skill does and when to use it. Claude uses it to decide when to load the skill. |\n| `when_to_use` | Extra trigger phrases or example requests, appended to the description. |\n| `argument-hint` | Autocomplete hint such as `[issue-number]`. |\n| `arguments` | Named positional arguments for `$name` substitution. |\n| `disable-model-invocation` | `true` stops Claude from loading it automatically; manual only. |\n| `user-invocable` | `false` hides it from the `\u002F` menu so only Claude uses it. |\n| `allowed-tools` | Tools pre-approved while the skill runs. It does not restrict other tools. |\n| `model`, `effort` | Override the model or effort for the turn. |\n| `context: fork` | Run the skill in a subagent (with `agent` to pick which). |\n| `paths` | Globs limiting automatic activation to matching files. |\n\n## How does Claude decide to use a skill?\n\nBy the description. Claude sees the name and description of every available skill and loads one when your request fits. That makes the description the most important line you write:\n\n- Lead with the use case. The combined `description` and `when_to_use` text is truncated at 1,536 characters in the skill listing, so put the key trigger first.\n- Say what it does and when to use it, in the words you would actually type: \"Use when the user asks to cut a release or bump the version\".\n- Test it with realistic prompts in a fresh session, with and without the skill. Context left over from writing the skill can hide gaps in the instructions.\n\nIf a skill has side effects (deploy, publish, send), set `disable-model-invocation: true` so it only ever runs when you type `\u002Fdeploy`. If it is background knowledge you never call by name, use `user-invocable: false`.\n\n## How do arguments and scripts work?\n\n`$ARGUMENTS` is everything typed after the name. `$0`, `$1` and so on pick one by position, and `arguments: [component, from, to]` lets you write `$component`, `$from`, `$to`. Quote values with spaces. If you use no placeholder, the arguments are appended as `ARGUMENTS: \u003Cvalue>`. Escape a literal dollar sign with a backslash.\n\nA skill can carry more than one file:\n\n```text\nrelease\u002F\n├── SKILL.md          # overview and navigation, keep under 500 lines\n├── reference.md      # read only when needed\n└── scripts\u002F\n    └── bump.sh       # executed, not loaded into context\n```\n\nMention the supporting files from `SKILL.md` so Claude knows when to read them. `${CLAUDE_SKILL_DIR}` resolves to the skill's folder, which lets you pre-approve a bundled script:\n\n```yaml\nallowed-tools: Bash(${CLAUDE_SKILL_DIR}\u002Fscripts\u002Fbump.sh *)\n```\n\nScripts are the efficient part: a script that Claude runs costs its output, not its source.\n\n## What are good first skills, and how do they relate to commands?\n\nPick a procedure you have explained twice:\n\n- Release: bump the version, update the changelog, tag, build.\n- New migration or new endpoint, following your conventions.\n- Pull request description from the branch diff.\n- A review checklist for your stack, run with `context: fork` so the reading stays out of your main context.\n- Triage: reproduce a bug from an issue number, in a fixed order of steps.\n\nKeep each skill to one job, under 500 lines, and write the steps in the order you would do them. Claude Code also ships bundled skills such as `\u002Fsimplify`, `\u002Floop` and `\u002Fdebug`; list what you have with `\u002Fskills`.\n\n### Skills and commands\n\nCustom slash commands have been merged into skills: a `.claude\u002Fcommands\u002Fdeploy.md` file and a `.claude\u002Fskills\u002Fdeploy\u002FSKILL.md` both give you `\u002Fdeploy`, and a skill wins on a name clash. See [Claude Code slash commands](\u002Fblog\u002Fclaude-code-slash-commands) for the command side. For deterministic behavior, such as always running a formatter after an edit, a hook is the better tool than a skill, since a skill is guidance Claude chooses to follow.\n\n## In Relais\n\nRelais sessions are real Claude Code sessions, and the composer offers `\u002F` for commands and skills. A Relais session template can name skills to use alongside standing rules for a session. See [features](\u002Ffeatures).","\u003Cp>A Claude Code skill is a folder containing a \u003Ccode>SKILL.md\u003C\u002Fcode> file: Markdown instructions with a short YAML header. Claude loads it when your request matches its description, or you run it yourself with \u003Ccode>\u002Fskill-name\u003C\u002Fcode>. Skills are where procedures live (how to cut a release, how to add a migration), so they do not take up room in your CLAUDE.md on every session.\u003C\u002Fp>\n\u003Ch2 id=\"what-is-a-skill-and-why-not-just-use-claude-md\">\u003Ca class=\"anchor\" href=\"#what-is-a-skill-and-why-not-just-use-claude-md\" aria-label=\"Link to this section\">#\u003C\u002Fa>What is a skill, and why not just use CLAUDE.md?\u003C\u002Fh2>\n\u003Cp>Both give Claude instructions, but they load differently. \u003Ca href=\"\u002Fblog\u002Fclaude-md-guide\">CLAUDE.md\u003C\u002Fa> is read at the start of every session, so it should hold short facts that are always true: commands, layout, conventions. A skill&#39;s description is always visible to Claude, but its full content only loads when it is invoked. That makes skills the right home for long, task-specific procedures.\u003C\u002Fp>\n\u003Cp>A good test: if you would write &quot;when I ask to X, do steps 1 to 6&quot;, it is a skill. If it is &quot;we use pnpm&quot;, it is CLAUDE.md.\u003C\u002Fp>\n\u003Cp>Skills live in these places:\u003C\u002Fp>\n\u003Cdiv class=\"table-wrap\">\u003Ctable>\u003Cthead>\u003Ctr>\u003Cth>Scope\u003C\u002Fth>\u003Cth>Path\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd>Personal, all your projects\u003C\u002Ftd>\u003Ctd>\u003Ccode>~\u002F.claude\u002Fskills\u002F&lt;name&gt;\u002FSKILL.md\u003C\u002Fcode>\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>Project, shared via git\u003C\u002Ftd>\u003Ctd>\u003Ccode>.claude\u002Fskills\u002F&lt;name&gt;\u002FSKILL.md\u003C\u002Fcode>\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>A subdirectory\u003C\u002Ftd>\u003Ctd>\u003Ccode>&lt;subdir&gt;\u002F.claude\u002Fskills\u002F&lt;name&gt;\u002FSKILL.md\u003C\u002Fcode>\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>Plugin\u003C\u002Ftd>\u003Ctd>\u003Ccode>&lt;plugin&gt;\u002Fskills\u002F&lt;name&gt;\u002FSKILL.md\u003C\u002Fcode>, used as \u003Ccode>\u002Fplugin-name:skill-name\u003C\u002Fcode>\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>Organization\u003C\u002Ftd>\u003Ctd>in the managed settings directory\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>If a name exists in several scopes, enterprise beats personal, and personal beats project. Claude Code picks up added, edited or removed skills within the current session, with one exception: if you create a top-level skills directory that did not exist when the session started, run \u003Ccode>\u002Freload-skills\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-write-a-skill-md\">\u003Ca class=\"anchor\" href=\"#how-do-you-write-a-skill-md\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you write a SKILL.md?\u003C\u002Fh2>\n\u003Cp>A minimal skill is a directory with one file. This one summarizes your uncommitted work:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"md\">\u003Ccode>---\nname: summarize-changes\ndescription: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.\n---\n\n## Current changes\n\n!`git diff HEAD`\n\nSummarize the changes in two or three bullets, then list any risks:\nmissing tests, changed public APIs, leftover debug code.\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>The line starting with \u003Ccode>!`\u003C\u002Fcode> runs the shell command before Claude sees the skill and substitutes its output, so the diff is already in the prompt. A failed command aborts the invocation. For multi-line commands, use a fenced block opened with \u003Ccode>```!\u003C\u002Fcode>. If you would rather block this feature, set \u003Ccode>&quot;disableSkillShellExecution&quot;: true\u003C\u002Fcode> in settings.\u003C\u002Fp>\n\u003Ch2 id=\"what-frontmatter-fields-matter\">\u003Ca class=\"anchor\" href=\"#what-frontmatter-fields-matter\" aria-label=\"Link to this section\">#\u003C\u002Fa>What frontmatter fields matter?\u003C\u002Fh2>\n\u003Cp>The frontmatter must start on the file&#39;s first line. Field names must match exactly; unknown fields are ignored without an error. The ones you will actually use:\u003C\u002Fp>\n\u003Cdiv class=\"table-wrap\">\u003Ctable>\u003Cthead>\u003Ctr>\u003Cth>Field\u003C\u002Fth>\u003Cth>What it does\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd>\u003Ccode>name\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>The name in the \u003Ccode>\u002F\u003C\u002Fcode> menu. Defaults to the directory name.\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>description\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>What the skill does and when to use it. Claude uses it to decide when to load the skill.\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>when_to_use\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Extra trigger phrases or example requests, appended to the description.\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>argument-hint\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Autocomplete hint such as \u003Ccode>[issue-number]\u003C\u002Fcode>.\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>arguments\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Named positional arguments for \u003Ccode>$name\u003C\u002Fcode> substitution.\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>disable-model-invocation\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>\u003Ccode>true\u003C\u002Fcode> stops Claude from loading it automatically; manual only.\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>user-invocable\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>\u003Ccode>false\u003C\u002Fcode> hides it from the \u003Ccode>\u002F\u003C\u002Fcode> menu so only Claude uses it.\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>allowed-tools\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Tools pre-approved while the skill runs. It does not restrict other tools.\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>model\u003C\u002Fcode>, \u003Ccode>effort\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Override the model or effort for the turn.\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>context: fork\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Run the skill in a subagent (with \u003Ccode>agent\u003C\u002Fcode> to pick which).\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>paths\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Globs limiting automatic activation to matching files.\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Ch2 id=\"how-does-claude-decide-to-use-a-skill\">\u003Ca class=\"anchor\" href=\"#how-does-claude-decide-to-use-a-skill\" aria-label=\"Link to this section\">#\u003C\u002Fa>How does Claude decide to use a skill?\u003C\u002Fh2>\n\u003Cp>By the description. Claude sees the name and description of every available skill and loads one when your request fits. That makes the description the most important line you write:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Lead with the use case. The combined \u003Ccode>description\u003C\u002Fcode> and \u003Ccode>when_to_use\u003C\u002Fcode> text is truncated at 1,536 characters in the skill listing, so put the key trigger first.\u003C\u002Fli>\n\u003Cli>Say what it does and when to use it, in the words you would actually type: &quot;Use when the user asks to cut a release or bump the version&quot;.\u003C\u002Fli>\n\u003Cli>Test it with realistic prompts in a fresh session, with and without the skill. Context left over from writing the skill can hide gaps in the instructions.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>If a skill has side effects (deploy, publish, send), set \u003Ccode>disable-model-invocation: true\u003C\u002Fcode> so it only ever runs when you type \u003Ccode>\u002Fdeploy\u003C\u002Fcode>. If it is background knowledge you never call by name, use \u003Ccode>user-invocable: false\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-arguments-and-scripts-work\">\u003Ca class=\"anchor\" href=\"#how-do-arguments-and-scripts-work\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do arguments and scripts work?\u003C\u002Fh2>\n\u003Cp>\u003Ccode>$ARGUMENTS\u003C\u002Fcode> is everything typed after the name. \u003Ccode>$0\u003C\u002Fcode>, \u003Ccode>$1\u003C\u002Fcode> and so on pick one by position, and \u003Ccode>arguments: [component, from, to]\u003C\u002Fcode> lets you write \u003Ccode>$component\u003C\u002Fcode>, \u003Ccode>$from\u003C\u002Fcode>, \u003Ccode>$to\u003C\u002Fcode>. Quote values with spaces. If you use no placeholder, the arguments are appended as \u003Ccode>ARGUMENTS: &lt;value&gt;\u003C\u002Fcode>. Escape a literal dollar sign with a backslash.\u003C\u002Fp>\n\u003Cp>A skill can carry more than one file:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"text\">\u003Ccode>release\u002F\n├── SKILL.md          # overview and navigation, keep under 500 lines\n├── reference.md      # read only when needed\n└── scripts\u002F\n    └── bump.sh       # executed, not loaded into context\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Mention the supporting files from \u003Ccode>SKILL.md\u003C\u002Fcode> so Claude knows when to read them. \u003Ccode>${CLAUDE_SKILL_DIR}\u003C\u002Fcode> resolves to the skill&#39;s folder, which lets you pre-approve a bundled script:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"yaml\">\u003Ccode>allowed-tools: Bash(${CLAUDE_SKILL_DIR}\u002Fscripts\u002Fbump.sh *)\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Scripts are the efficient part: a script that Claude runs costs its output, not its source.\u003C\u002Fp>\n\u003Ch2 id=\"what-are-good-first-skills-and-how-do-they-relate-to-commands\">\u003Ca class=\"anchor\" href=\"#what-are-good-first-skills-and-how-do-they-relate-to-commands\" aria-label=\"Link to this section\">#\u003C\u002Fa>What are good first skills, and how do they relate to commands?\u003C\u002Fh2>\n\u003Cp>Pick a procedure you have explained twice:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Release: bump the version, update the changelog, tag, build.\u003C\u002Fli>\n\u003Cli>New migration or new endpoint, following your conventions.\u003C\u002Fli>\n\u003Cli>Pull request description from the branch diff.\u003C\u002Fli>\n\u003Cli>A review checklist for your stack, run with \u003Ccode>context: fork\u003C\u002Fcode> so the reading stays out of your main context.\u003C\u002Fli>\n\u003Cli>Triage: reproduce a bug from an issue number, in a fixed order of steps.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Keep each skill to one job, under 500 lines, and write the steps in the order you would do them. Claude Code also ships bundled skills such as \u003Ccode>\u002Fsimplify\u003C\u002Fcode>, \u003Ccode>\u002Floop\u003C\u002Fcode> and \u003Ccode>\u002Fdebug\u003C\u002Fcode>; list what you have with \u003Ccode>\u002Fskills\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Ch3 id=\"skills-and-commands\">\u003Ca class=\"anchor\" href=\"#skills-and-commands\" aria-label=\"Link to this section\">#\u003C\u002Fa>Skills and commands\u003C\u002Fh3>\n\u003Cp>Custom slash commands have been merged into skills: a \u003Ccode>.claude\u002Fcommands\u002Fdeploy.md\u003C\u002Fcode> file and a \u003Ccode>.claude\u002Fskills\u002Fdeploy\u002FSKILL.md\u003C\u002Fcode> both give you \u003Ccode>\u002Fdeploy\u003C\u002Fcode>, and a skill wins on a name clash. See \u003Ca href=\"\u002Fblog\u002Fclaude-code-slash-commands\">Claude Code slash commands\u003C\u002Fa> for the command side. For deterministic behavior, such as always running a formatter after an edit, a hook is the better tool than a skill, since a skill is guidance Claude chooses to follow.\u003C\u002Fp>\n\u003Ch2 id=\"in-relais\">\u003Ca class=\"anchor\" href=\"#in-relais\" aria-label=\"Link to this section\">#\u003C\u002Fa>In Relais\u003C\u002Fh2>\n\u003Cp>Relais sessions are real Claude Code sessions, and the composer offers \u003Ccode>\u002F\u003C\u002Fcode> for commands and skills. A Relais session template can name skills to use alongside standing rules for a session. See \u003Ca href=\"\u002Ffeatures\">features\u003C\u002Fa>.\u003C\u002Fp>\n",[15,18,21,24,27,30,33],{"id":16,"text":17},"what-is-a-skill-and-why-not-just-use-claude-md","What is a skill, and why not just use CLAUDE.md?",{"id":19,"text":20},"how-do-you-write-a-skill-md","How do you write a SKILL.md?",{"id":22,"text":23},"what-frontmatter-fields-matter","What frontmatter fields matter?",{"id":25,"text":26},"how-does-claude-decide-to-use-a-skill","How does Claude decide to use a skill?",{"id":28,"text":29},"how-do-arguments-and-scripts-work","How do arguments and scripts work?",{"id":31,"text":32},"what-are-good-first-skills-and-how-do-they-relate-to-commands","What are good first skills, and how do they relate to commands?",{"id":34,"text":35},"in-relais","In Relais",[37,42,48],{"slug":38,"title":39,"description":40,"category":7,"categoryId":8,"keyword":41,"date":10,"minutes":11},"claude-code-beginners-guide","Claude Code for beginners: install, first session, habits","Install Claude Code, run your first session and learn the habits that matter: specific prompts, plan before edit, CLAUDE.md, small commits, a clean context.","claude code for beginners",{"slug":43,"title":44,"description":45,"category":7,"categoryId":8,"keyword":46,"date":10,"minutes":47},"claude-code-hooks","Claude Code hooks: run a script on every tool call","Claude Code hooks run your own script before or after a tool call. Learn the config format, exit codes and three working examples you can paste today.","claude code hooks",6,{"slug":49,"title":50,"description":51,"category":7,"categoryId":8,"keyword":52,"date":10,"minutes":11},"claude-code-permission-modes","Claude Code permission modes explained (and when to use each)","Default, acceptEdits, plan, auto, dontAsk and bypassPermissions: what each Claude Code permission mode allows, how to switch, and which one fits which job.","claude code permission modes",1794931098788]