Custom commands and skills
Choose the commands for custom commands and skills and follow their availability rules and concrete examples.
Key takeaways
- Define a skill directory, control who can invoke it, and pass task-specific arguments.
Current Model
Custom commands and skills are now one slash-command experience. A file at .claude/commands/deploy.md
and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way. Existing
.claude/commands/*.md files keep working, but new workflows should usually use
.claude/skills/<name>/SKILL.md because skills add a directory for supporting files, richer frontmatter
controls, scripts, dynamic context injection, and the ability for Claude to load them automatically when
relevant. If a skill and a command share the same name, the skill takes precedence.
Both you and Claude can invoke a skill by default: you type /skill-name, and Claude can also load it
automatically when its description matches your request.
Recommended Shape
A skill is a directory whose SKILL.md is the entrypoint. Other files are optional and load only when
referenced.
.claude/skills/
release-check/
SKILL.md
checklist.md
scripts/
collect-release-info.sh---
name: release-check
description: Check release risk, test coverage, and documentation gaps. Use when preparing a release or asked to assess merge readiness.
disable-model-invocation: true
allowed-tools: Read Grep Bash
argument-hint: [release-target]
---
Release target: $ARGUMENTS
Current effort: ${CLAUDE_EFFORT}
## Recent changes
!`git diff HEAD`
1. Summarize the changed area.
2. Check required tests and docs against checklist.md.
3. Return blockers first, then follow-up risks.The directory name (release-check) becomes the command you type. The frontmatter name only sets the
display label in skill listings; it does not change what you type after / (except for a plugin-root
SKILL.md).
Key Controls
Only description is recommended; every field is optional.
| Control | Use it when |
|---|---|
description | Claude needs to decide whether the skill is relevant. Put the key use case first; the combined description + when_to_use is capped at 1,536 characters. |
when_to_use | You want extra trigger phrases or example requests appended to the description. |
disable-model-invocation: true | The workflow has side effects and should only run when the user types it. Also keeps it out of Claude's context and out of preloaded subagents. |
user-invocable: false | The skill is background knowledge, not a user command, so it should be hidden from the / menu (but Claude can still load it). |
allowed-tools | The skill needs pre-approved tools while still respecting global permissions. Space-, comma-separated, or a YAML list. |
disallowed-tools | Certain tools must never run while the skill is active (e.g. blocking AskUserQuestion in a background loop). |
argument-hint | You want an autocomplete hint for expected arguments, e.g. [issue-number]. |
arguments | You want named positional placeholders ($name) instead of indexes. |
$ARGUMENTS, $ARGUMENTS[N], $N | The command needs user-supplied input. $0 is the first argument, $1 the second. |
${CLAUDE_EFFORT}, ${CLAUDE_SESSION_ID}, ${CLAUDE_SKILL_DIR} | The skill should adapt to current effort, log per session, or reference bundled files. |
model, effort | The skill should run at a specific model or effort level for its turn. |
context: fork (+ agent) | The skill should run in an isolated subagent context with its content as the prompt. |
paths | The skill should auto-activate only for files matching given globs. |
Who can invoke
| Frontmatter | You can invoke | Claude can invoke |
|---|---|---|
| (default) | Yes | Yes |
disable-model-invocation: true | Yes | No |
user-invocable: false | No | Yes |
Note: user-invocable: false only hides the skill from the / menu; it does not block Claude's Skill
tool. Use disable-model-invocation: true to stop Claude from invoking it.
Dynamic Context Injection
Lines of the form !`<command>` run before the skill is sent to Claude, and the command output
replaces the placeholder. This is preprocessing, not something Claude executes — Claude only sees the
final rendered text.
## Current changes
!`git diff HEAD`The inline form is only recognized when ! starts a line or follows whitespace. For multi-line commands,
use a fenced block opened with ```!. You can disable this behavior globally with
"disableSkillShellExecution": true in settings.
When to Keep .claude/commands
Keep a legacy command file when the prompt is short, has no supporting files, and is already widely used by the team — those files still work and support the same frontmatter. Move it to a skill when you need scripts, examples, references, explicit invocation controls, or automatic loading by Claude.
Validation
- Run
/skillsand search for the command name (presstto sort by token count). - Invoke the command with a sample argument.
- Confirm whether Claude can invoke it automatically or only the user can (see the table above).
- Keep
SKILL.mdconcise — under ~500 lines — and move long references into separate files. Once invoked, the body stays in context for the rest of the session, so every line is a recurring token cost. - Treat
allowed-toolsas a permission grant, not just documentation. Review project skills before trusting a repo, since a skill can grant itself broad tool access. - If a skill is added or edited on disk mid-session, run
/reload-skillsto pick it up without restarting.
Related Commands
/skills: list and filter available skills, and hide skills from Claude or the/menu./reload-skills: re-scan skill and command directories so on-disk changes apply without a restart. (Available from v2.1.152.)/plugin: distribute shared skills and commands as plugins./reload-plugins: reload active plugins to apply pending changes without restarting./fewer-permission-prompts: scan transcripts for common read-only Bash and MCP calls and add a prioritized allowlist to project.claude/settings.json./config(alias/settings): adjust theme, model, output style, and other preferences.
For the full built-in command list, see the official commands reference. For skill authoring details, see the skills guide.