D3 · Claude Code › Cluster 4 · Slash Commands

4.3 · Command Frontmatter

allowed-tools · model · argument-hint

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.

KeyPurpose
descriptionWhat 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-hintHint shown during autocomplete for expected args, e.g. [issue-number] or [filename] [format].
allowed-toolsTools Claude may use without asking while the command is active. Space- or comma-separated, or a YAML list.
modelModel to use while active (same values as /model, or inherit). Override lasts the current turn; the session model resumes next prompt.
disable-model-invocationtrue 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

flowchart TD F["Command file
--- 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
⚠️ For a project command, 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

Trap: "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.
Trap: "The model override sticks for the rest of the session." → It applies for the current turn only; your session model resumes on the next prompt.
Trap: "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.)
Trap: "Frontmatter is required." → It is optional. A bare Markdown file is a valid command; only 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.