A Command is a single-purpose prompt template invoked as /name. One agent, one pass, one output. Commit it. Version it. Improve it.

Primitive

Command

First, what it isn't

Command vs Skill vs Skill Pack

this node

⚡

Command

Single markdown file

invokeexplicit — /name

roleone agent, one pass, one artifact

🧩

Skill

Markdown that orchestrates

invokeexplicit — by script or command

rolecoordinates multiple agents + gates

📚

Skill Pack

Directory with SKILL.md

invokeimplicit — auto-loaded by description match

roleon-demand knowledge base

If it can be done by one agent in one pass, it's a Command.

If it needs multiple agents or validation gates, it's a Skill.

Anatomy

Six sections. One optional. In this order.

.claude/commands/feature.md

01Frontmatter

YAML: allowed-tools, description, argument-hint.

---

allowed-tools: Read, Write, Edit, Grep

description: Generate a feature plan and save to specs/

argument-hint: [issue_number] [adw_id]

---

02# Purpose

1–3 sentences: what it produces, for whom. Action verb first.

03## Variables

Dynamic args first, then static constants. UPPER_SNAKE_CASE.

USER_REQUEST: $1

EXPERTISE_FILE: $2

OUTPUT_DIR: specs/

MAX_LINES: 1000

04## Instructions

Hard rules that apply across ALL workflow steps. constraints

05## Workflow

Numbered sequential steps. Action verbs. Reference variables by name. sequence

06## Report

Exact output contract. Format, required fields, destination.

07## Codebase Structure

Only when the command navigates a specific layout. optional

No ## Notes, ## Tips, or ## Context. Extra sections dilute the contract.

The easy-to-confuse pair

Instructions are rules. Workflow is sequence.

InstructionsCONSTRAINTS

bullet list, unordered

• •Do not write or modify files. Read-only.
• •Always cite file paths with line numbers.
• •If question is off-domain, stop and clarify.

Applies to every step of every invocation.

WorkflowSEQUENCE

numbered, ordered

• 1.Read EXPERTISE_PATH to load mental model
• 2.Validate claims against codebase via Grep
• 3.Answer USER_QUESTION per Report format

Executed in order, once per invocation.

Conflate them and your rules stop applying — a constraint buried in step 2 doesn't govern step 3.

Namespacing

Subdirectories = namespaced invocations.

.claude/commands/

├──feature.md→/feature

├──bug.md→/bug

├──experts/

│   └──database/

│       └──question.md→/experts:database:question

└──craft/

├──agent.md→/craft:agent

├──command.md→/craft:command

└──hook.md→/craft:hook

Namespace when there's a real grouping — a domain family or a meta-command set.

Don't nest just to reduce file count.

The non-negotiable rule

One Command. One job. One output.

Two jobs in one Command

/classify_and_implement

job 1: classify issue → feature | bug | chore

job 2: implement the plan → code changes

When output is wrong, you can't tell which job failed. Can't eval it. Can't version it. Can't improve it precisely.

One job per Command

/classify_issue → /feature → /implement

/classify_issue returns a type

/feature produces a plan

/implement executes the plan

Each step is independently evaluable. When something breaks, the failing Command is obvious. Each can be improved in isolation.

Where Commands live

User prompt layer. Not system prompt.

System prompt

Law

Rules for every agent run in this project. Durable, broad, lean.

CLAUDE.md

settings.json

User prompt

Per-task input

Scoped to one invocation. Ephemeral, focused.

Commands ←

AGENT_SYSTEM.md

task descriptions

Put a Command-worth of content into the system prompt and every unrelated run pays the context tax.

Commands stay ephemeral; system prompt stays lean.

The usual failure modes

Anti-patterns to watch for

✗

description that doesn't say when to invoke

Trigger matching breaks; command becomes manual-only.

✗

Maximalist allowed-tools

Grants more blast radius than the command needs. Security smell.

✗

Vague Instructions like "improve the code"

Precision is the entire value. Specify the file, the pattern, the case.

✗

Missing Report section

Agent completes, reports "done." Downstream parsing fails on the first shape drift.

✗

More than ~15 Instructions bullets

Command is doing too much. Split or sequence.

✗

Extra sections — ## Notes, ## Tips, ## Context

The 6-section contract is what keeps commands evaluable. Fold content into the existing sections.

The discipline

A Command is a commit-able function call for agents.

Single purpose, single output, single file. The contract is what makes it improvable — and what keeps the system building knowledge instead of re-deriving it every time.