A skill is a way to frame a repeatable procedure as a product: a directory with a SKILL.md file and optional supporting files. It appears as a slash command and can be automatically matched by Claude via its description. The old commands in .claude/commands/*.md remain compatible, but a directory skill is more convenient - into it go not only the instruction but scripts, examples and references. The key difference from a command: a skill auto-triggers by task relevance, while a command is an explicit human invocation.
Skills live in several places with clear name semantics. A project skill is in .claude/skills/<command>/SKILL.md, a user skill in ~/.claude/skills/, a plugin skill in the plugin's skills/, legacy commands in .claude/commands. In project and user skills the command name is taken from the directory name, and the name field in the frontmatter changes the displayed label; in a plugin skill the command is namespaced as /plugin-name:skill-name. This lets you keep same-named skills from different sources without conflicts.
A good skill starts with an honest frontmatter and a verifiable body. It helps to see a whole example once - the review-change skill: with a description for auto-matching, disable-model-invocation, an argument-hint, declared arguments and a narrow allowed-tools, and in the body a numbered review procedure. Named arguments are declared in the frontmatter, and this is safer than shell-like guesses: in the body you have $ARGUMENTS, indexed $0, named $base and utility variables like ${CLAUDE_SKILL_DIR}.
Arguments have a substitution subtlety to know. A missing indexed argument stays literal in the text, and a missing named one becomes an empty string - so in the body you explicitly set a fallback instruction for an empty value. Otherwise a skill invoked without an argument will substitute emptiness and behave differently than intended. A skill's verifiability starts exactly here: with clear behavior for a missing and for a given argument.
The frontmatter is a map of decisions, and each field is justified by the skill's role, not opened for completeness. description and when_to_use are needed for auto-matching; disable-model-invocation - when only a human should launch it; allowed-tools and disallowed-tools - for pointed tool control; model and effort - when quality and cost are measured; context: fork - when noisy work is moved into a separate context. The full map of key fields is conveniently kept before your eyes as a table.
It helps to gather the key frontmatter fields into a table once, to choose consciously. Below is such a map. Important caveats: allowed-tools acts only on the invocation turn and must not be broad; context: fork isolates the context, but the result still affects the main session; disable-model-invocation also prevents automatic preload into a subagent and scheduled invocation. A field is opened not for completeness but for the skill's concrete need.
| Frontmatter field | Use when |
|---|---|
| description / when_to_use | Reliable auto-matching is needed |
| disable-model-invocation | Only a human should launch it |
| user-invocable: false | It is background knowledge, not a menu command |
| allowed-tools / disallowed-tools | Pointed tool control on the turn |
| model / effort | Quality and cost are measured |
| context: fork / agent | Noisy work into a separate context |
Progressive disclosure keeps the context cheap. The skill listing shows only the name and description, while the full body loads on activation and stays in the context of subsequent turns. So SKILL.md is kept short: a large specification is moved into references/, scripts into scripts/, and they are referenced via ${CLAUDE_SKILL_DIR} rather than the current working directory. So the skill loads the heavy only when truly needed rather than taking up context always.
A skill's quality is checked as a product, not by eye. You gather 5-10 real prompts - positive, negative and boundary; check the automatic trigger and the absence of false positives; check the granted tools and the negative security case; compare the result with a manual checklist; version the changes. Skills and agents are re-read live after an edit, but if a directory is created for the first time in an already running old session, a restart remains a sensible diagnostic. Frame the repeatable as a product - and check it as one.
---
name: Review change
description: Review the current change for correctness, security, regressions,
and missing tests. Use after implementation and before commit.
disable-model-invocation: true
argument-hint: "[base-ref]"
arguments: [base]
allowed-tools: Read, Grep, Glob, Bash(git diff:*)
---
If `$base` is non-empty, review the diff against that Git reference.
Otherwise review the working tree and staged diff.
1. Read the complete diff and relevant callers.
2. Rank findings by severity, include file paths.
3. If there are no findings, state residual risks and verification performed.