commands-authoring

Writing Slash Commands

Commands specify constraints and mode, not instructions. Claude already knows how to do most things — commands tell it what to do differently.

Structure

---
description: One-line description (shows in /help)
allowed-tools: Tool(pattern:*), Tool(pattern:*)
argument-hint: [arg1] [arg2]
---

Prompt content. Set role, constraints, then get out of the way.

Features

• $ARGUMENTS — all args as string, or $1, $2 for positional
• !`git status` — inline bash execution (output included in context)
• @path/to/file.ts — file reference (contents included inline)

Bash execution requires matching allowed-tools declarations.

Key Rules

1. Minimal tokens — every line costs context
2. Constraints > procedures — say what to do differently, not how
3. Don't restate knowledge — skip things Claude already knows
4. Limit allowed-tools — only enable what's needed
5. One concern — focused commands, not kitchen sinks

Invocation Control

Most commands should be user-only or agent-only — rarely both.

Default to disable-model-invocation: true for most commands. Agent auto-invocation is a footgun — commands that modify state, run tools, or trigger workflows should require explicit user intent. Reserve agent-invocable commands for read-only reference or context-injection where autonomous discovery is the point.

Other Frontmatter

When to Use Commands vs Skills

Anti-Patterns

• Missing description (won't appear in /help or Skill tool)
• allowed-tools: Bash(*) (overly permissive)
• Absolute file paths (use @ references instead)
• No argument-hint when args are expected
• Long procedural instructions (use constraints instead)