CONCEPT YAML at the top configures the command
A command (or skill) file may open with a YAML frontmatter block between ---
markers. Everything below the closing --- is the prompt body. The frontmatter is where you tune
how the command behaves: what it is called, whether Claude may auto-trigger it, which tools it can use
without asking, and which model runs it. All fields are optional — only
description is recommended, so Claude knows when the skill applies.
| Key | Purpose |
|---|---|
description | What the command does and when to use it. Shown in the menu; Claude uses it to decide auto-invocation. If omitted, the first paragraph of the body is used. |
argument-hint | Hint shown during autocomplete for expected args, e.g. [issue-number] or [filename] [format]. |
allowed-tools | Tools Claude may use without asking while the command is active. Space- or comma-separated, or a YAML list. |
model | Model to use while active (same values as /model, or inherit). Override lasts the current turn; the session model resumes next prompt. |
disable-model-invocation | true stops Claude from auto-loading it — only you can trigger it with /name. Default false. |
allowed-tools grants permission — it does not restrict. Every tool stays
callable; listed tools simply skip the approval prompt while the command runs. To remove tools use
disallowed-tools; to block globally use permission deny rules (Cluster 3).CONCEPT Manual-only workflows: disable-model-invocation
By default both you and Claude can invoke a command. For anything with side effects — /deploy,
/commit, /send-slack-message — add disable-model-invocation: true
so Claude never decides to run it on its own. You keep the trigger; Claude keeps its hands off. This also keeps
the command's description out of Claude's context until you invoke it.
DIAGRAM How frontmatter shapes a run
--- frontmatter --- + body"] --> DESC["description → menu + auto-match"] F --> DMI{"disable-model-invocation?"} DMI -->|"true"| MAN["🟠 You-only trigger"] DMI -->|"false (default)"| BOTH["🟢 You or Claude trigger"] F --> AT["allowed-tools → skip approval
for listed tools"] F --> MOD["model → run on this model
for the turn"] F --> AH["argument-hint → autocomplete hint"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef man fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class BOTH ok; class MAN man;
CODE A fully-annotated command file
A commit helper that runs manually, pre-approves the git tools it needs, and hints at its argument:
--- description: Stage and commit the current changes argument-hint: [message] disable-model-invocation: true allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *) model: sonnet --- Stage all changes and commit them with a clear message. # $ARGUMENTS becomes the commit message the user typed. Use this as the commit subject: $ARGUMENTS
allowed-tools only takes effect after you accept
the workspace-trust dialog for that folder — the same gate as permission rules in
.claude/settings.json. Review project commands before trusting a repo; one can grant itself broad
tool access.TRADE-OFFS Pre-approving tools with allowed-tools
✅ List the tools you trust
- No approval prompt mid-workflow — smooth runs
- Scope tightly, e.g.
Bash(git commit *) - Intent is explicit and reviewable in the file
⚠️ Over-broad grants
Bash(*)hands over the whole shell- A committed command can self-grant access
- Only as safe as your review + workspace trust
EXAM TRAPS
allowed-tools restricts the command to only those tools." → It
grants, not restricts. All tools stay available; listed ones just skip the permission prompt. Use
disallowed-tools to remove tools.model override sticks for the rest of the session." → It applies
for the current turn only; your session model resumes on the next prompt.disable-model-invocation stops me from running it too." → No —
it only stops Claude from auto-triggering it. You can still run /name. (To hide it from the
menu, that is user-invocable: false.)description is recommended.PRACTICE
Q1 · You want /deploy to be runnable only when you type it, never auto-run by Claude. Which key?
disable-model-invocation: true. It keeps the command manual-only and keeps
its description out of Claude's context until you invoke it.
Q2 · Does allowed-tools: Bash(git commit *) block Claude from using other tools?
No. It only pre-approves that git command so it runs without a prompt. Every other tool is still available and still governed by your normal permission settings.
Q3 · What does argument-hint do, and where is it seen?
It provides a hint (e.g. [issue-number]) shown during
autocomplete so you know what arguments the command expects. It does not enforce anything.