Commands vs Agents

Two concerns quietly collapse into one file: the workflow (what steps run, in what order) and the expertise (how to do the job well). Separate them and either can change without touching the other.

Why this, for you: Lesson 8 trimmed an agent's own knowledge with skills. This lesson is the next cut: pulling the orchestration out of the expert entirely. Get the boundary right and one reviewer agent serves five commands — and a pipeline gains a step without anyone editing the reviewer.

In agent-driven projects, commands define what to do and agents define who does it. Commands own the pipeline; agents own the craft. The win is composability: change either side without rewriting the other.

1 The split: workflow vs. expertise

A command is a workflow definition — fetch the issue, research, draft, review, open a PR. It names the steps, sequences them, and defines what passes between them. It does not know how to research or draft; that's someone else's job. An agent carries expertise — role, quality bar, constraints, relevant skills — and doesn't know, or need to know, which pipeline called it.

Concern	Command	Agent
Step sequence & branching	Yes	No
Delegation targets	Yes	No
Quality bar & domain knowledge	No	Yes
Skill references	No	Yes
Success criteria	Handoff-level	Execution-level

This mirrors how effective teams operate: a project manager defines the process; specialists execute the work. The process is separable from the people — and in agent terms, separable files.

2 Why it pays: composability

When orchestration and expertise live in one file, every change touches both. Adding a pipeline step means editing the expert; tightening the quality bar means editing the pipeline. Separated, the same content-writer serves a draft-content and an implement-issue command, and the same research-topic command can delegate to a different specialist by domain — neither change touches the other file.

# .claude/commands/implement-issue.md — the pipeline only 1. gh issue view $ISSUE # fetch 2. delegate to @researcher # research 3. delegate to @content-writer # draft to their quality bar 4. gh pr create # open PR # the command never states HOW to research or draft — that's the agent's file

Extend the command with a new review stage without editing content-writer.md; tighten the writer's quality bar without touching any command. The two evolve at different rates, for different reasons.

3 The anti-pattern: the monolithic command

The failure mode is a command file that embeds the full domain instructions for every agent it calls. Recognizable symptoms:

Commands exceed 300 lines because they inline all agent knowledge.
The same expert instructions are copy-pasted across multiple commands.
Updating a quality standard means editing N command files instead of one agent definition.
Swapping in a specialist agent requires rewriting the command.

It's the same disease Lesson 8 diagnosed inside a single agent — knowledge in the wrong place — now visible one level up, between the workflow and the expert.

When the split is just indirection

The pattern derives from separation-of-concerns and the single-responsibility principle — and inherits their trade-off: better long-term maintainability at the cost of upfront complexity. It backfires in three cases. Single-use pipelines: if one command is run by exactly one agent, never reused, the boundary is pure indirection. Rapidly changing scope: when pipeline and expertise are both in flux, the boundary forces two-file edits to stay coherent and slows iteration. Solo projects without reuse: the abstraction is notional until the same agent genuinely serves multiple callers. Separate when reuse is real, not on reflex.

↪ Your win: workflow in commands, craft in agents

Commands own orchestration — what runs, when, and to whom it delegates.
Agents own execution — how the job is done and to what standard.
One agent, many commands — reuse the expert without copy-paste.
Swap targets without rewriting pipelines — point a command at a new specialist freely.
Watch for the 300-line monolith — embedded expertise is the signal to split.

Retrieval practice — recall, don't peek

Question 1In the commands/agents split, a command owns…

Question 2The payoff of separating workflow from expertise is that…

Question 3A 300-line command that inlines every agent's instructions is…

Question 4The split is mostly indirection when…

Question 5 · spaced recall from Lesson 08Progressive disclosure keeps an agent definition small by…

Ask me anything. Want to factor one of your monolithic command files into a command plus reusable agents, or see how this layers over Lesson 8's skills? Next in Part 5: Plan Mode & Plan-First — making the agent prove it understands before it writes a line.