Agentics

Appearance

A reusable agent prompt is a .md file with five named sections — Variables, Instructions, Relevant Files, Format, Report — not prose.

Pattern

Prompt Template Authoring ​

The five-section anatomy

Each section does one job. Don't conflate them. ​

.claude/commands/feature.md

template

## Variables

Declare interpolation slots$1, $2, $3, $ARGUMENTS — invoker supplies, template substitutes

## Instructions

High-level directivesTHINK HARD · be surgical · research the codebase first

## Relevant Files

Glob patterns the agent must read before actingbounds context — no under-read, no over-read

## Format

The exact output contractmarkdown skeleton for plans · JSON schema for structured output

## Report

What the agent returns on completiona path · a summary · a JSON object

Conflating these collapses the template back into prose. Separate them even when the template is small — the discipline is the boundary.

Prose prompt vs templated prompt

Same intent. One drifts each invocation. One doesn't. ​

Free-form prosedrifts every run

"Please look at issue 47 and fix the bug in the auth module. Return something useful when done."

  • no variable slots — not reusable
  • no declared output — downstream parsing fails
  • no files-to-read — agent guesses scope
  • cannot be evaluated against a fixture

Five-section templatereproducible

## Variables$1=issue, $2=sha

## Relevant Files src/auth/*.py

## Format plan.md skeleton

## Report { path, summary }

  • invoke N times with different args
  • downstream tools parse the output
  • context bounded — minimum viable reads
  • can be run as an eval on a fixture

The template isn't more verbose — it's structured. Structure is what makes the prompt a harness instead of a one-off wish.

How variables flow in

CLI args → slots → resolved prompt. ​

Positional args at invocation time replace declared slots in the template body. One template, N invocations.

1. Invocation

claude -p

"/feature

47

cc73faf1

'{...JSON...}'"

→

2. Resolved prompt

Fix issue 47

at commit cc73faf1

using payload

{...JSON...}

Read src/auth/*.py

Return plan.md

$1→47

$2→cc73faf1

$3→{JSON}

Structure is checked in. Context is injected at run time. The template describes the task shape; the args supply the particulars.

What breaks when a section is missing

Each omission fails in a distinct, predictable way. ​

no variable slots

Every run is a one-off ​

No reproducibility. Prompts Are Evals becomes impossible — you can't test what you can't re-run with different inputs.

no declared format

Output shape paraphrases ​

Agent produces whatever looks appropriate. Downstream parsing fails intermittently — breaks on the first model update.

no relevant-files slot

Context starves or floods ​

Agent reads nothing and hallucinates, or reads everything and pollutes. Either way quality drops.

The five sections aren't stylistic — each is a forcing function against a specific failure mode.

Minimum viable, plus leverage

Four required. Two more when the template must travel. ​

Start at the minimum. Promote a prompt from prose to template the second time you use it — not the first.

The discipline ​

A reusable prompt is a file with named sections, not a paragraph you rewrote from memory.

Structure turns the prompt into a harness: variables make it reproducible, format makes it parseable, files-to-read bound its context, and report closes the loop. Every slash command and every phase of an ADW earns its keep this way.