Slash command authoring standards

A slash command is a custom shortcut invoked by typing /<name> in Claude Code — the most direct way to package a prompt or workflow for repeat use. Commands ship standalone at commands/<name>.md or bundled at plugins/<plugin>/commands/<name>.md.

This page is two layers: Anthropic’s official guidance, then the RBA tailoring on top.

Anthropic’s best practices

Source: Claude Code — Slash commands.

A slash command is a Markdown file. The filename (minus .md) is the command name; subdirectories create namespaces. Anthropic’s core guidance:

Frontmatter (all optional)

---
description: <one sentence>          # shown in the /help list and the autocomplete menu
argument-hint: "<arg placeholders>" # shown in the autocomplete menu
allowed-tools: Read, Grep           # tools the command may use (required if it runs bash)
model: sonnet                       # optional model override
disable-model-invocation: false     # optional — prevent Claude auto-running it
---

None of these are required for the command to work, but description and argument-hint are strongly recommended for discoverability.

Arguments, bash, and file references

Anthropic supports three substitution mechanisms in the command body:

• $ARGUMENTS — everything the user typed after the command name.
• $1, $2, … — individual positional arguments.
• ! prefix — a line beginning with ! is executed as a bash command and its output is inlined (requires allowed-tools to permit it).
• @ prefix — @path/to/file inlines that file’s contents.

Skills supersede commands for most new work

Anthropic positions Skills as the richer, auto-discoverable mechanism; slash commands remain the right tool for explicitly user-invoked shortcuts. Reach for a command when the user must deliberately type it, not when you want Claude to apply a methodology on its own.

How RBA tailors this

Read this first: prefer a skill

RBA makes Anthropic’s “skills are richer” guidance a default. For new work, write a skill, not a command, unless one of two narrow cases applies:

1. Strict invocation-only — the user MUST type the command and Claude should not auto-suggest it.
2. Porting an existing one-shot prompt — skill structure would add no value.

	Skill	Command
Discovery	Auto-suggested from context	User types /<name>
Metadata	name, description, argument-hint, allowed-tools, supporting files	mostly description
Composability	Can compose with other skills	Standalone
Plugin/marketplace	First-class	Supported, but legacy for new work

If neither narrow case applies, write a skill.

Frontmatter — RBA additions

---
name: <command-name>             # RBA: required — must match the filename (slug = name)
description: <one sentence>       # required in practice — Anthropic's rules apply
primitive: true                  # optional — set only when this is a cross-cutting foundation primitive
argument-hint: "<placeholder>"   # recommended when the command takes input
allowed-tools: Read, Grep        # RBA: least-privilege, never bare Bash
---

Anthropic treats every field as optional; RBA requires name (slug = filename). Standalone commands may set optional facets (platforms, disciplines, outcomes, lifecycle, tags) or primitive: true for foundation primitives. Plugin-bundled commands inherit primitive from the plugin’s rba-meta.json and must not redeclare it. See plugin standards for the facet model.

Naming (RBA)

• Filename kebab-case.md; name field matches; body title prefixed with / — # /format-staged.
• Don’t shadow a built-in (/help, /clear, /init, /review, …).

Tool allowlist (RBA tightens)

Same least-privilege rule as skills. Default-deny Bash; whitelist specific commands:

allowed-tools: Read, Grep, Bash(git status, git diff *)

Quality checklist

1. description and argument-hint are set so the command is discoverable (Anthropic).
2. There is a documented reason this is a command and not a skill (RBA).
3. Frontmatter has name; standalone commands may set optional facets or primitive: true (RBA).
4. Slug = name = filename (RBA).
5. The persona is domain-specific.
6. allowed-tools is least-privilege with no bare Bash (RBA).
7. The command name doesn’t shadow a built-in.
8. The command produces useful output on a representative input.

Anti-patterns

• A command that should be a skill (almost all of them — RBA default)
• Command name shadowing a built-in
• Using ! bash execution without declaring allowed-tools (won’t run — Anthropic requirement)
• Open-ended Bash(*) allowlist
• Generic persona
• Missing argument-hint when the command takes input