agent-prompt-patterns

What this skill does

# Agent Prompt Patterns

> Battle-tested patterns for agents that ship, not agents that demo.
> If your agent works in a live-fire notebook but breaks in production, you have a demo, not an agent.

---

## When to Use

- Designing a new agent's behavioral rules and operating manual
- An agent is hallucinating completions, skipping steps, or claiming work it didn't do
- Building multi-agent pipelines where output quality compounds (or collapses)
- Setting up human-in-the-loop approval tiers for different risk levels
- Enforcing reliability in automated workflows (cron jobs, scheduled tasks, pipelines)
- Writing AGENTS.md or operating manuals for production agent workspaces
- Debugging why an agent keeps violating rules you've already stated
- Evaluating whether an agent should exist at all (deletion test)
- Building harnesses that make autonomy safe and useful

## When NOT to Use

- One-shot prompts with no agent persistence — these patterns assume continuity
- Pure chatbot / conversational UX with no action-taking capability
- Academic prompt engineering research — these are production patterns, not benchmarks
- Agents with no filesystem, no tool access, and no side effects — nothing to harness
- You're still in the "make it work at all" phase — get basic functionality first, then harden

---

## 1. Consumer-First Design

**Principle:** Every agent output must have a named consumer. If nobody uses the output, the agent shouldn't exist.

This is the most important pattern because it kills bloat before it starts. Agents proliferate. Each one feels useful when you build it. Six months later you have 14 agents and can't remember what half of them do.

### The Deletion Test

Ask: *If I delete this agent, which other agent's work breaks?*

If the answer is "nothing" or "I'm not sure," the agent is a vanity project.

```markdown
# Agent Registry (in AGENTS.md)

## daily-digest
- **Consumers:** Sam (morning briefing), weekly-report agent (aggregation)
- **Deletion impact:** Sam loses morning summary, weekly-report loses daily inputs
- **Verdict:** KEEP

## inbox-sorter
- **Consumers:** None identified
- **Deletion impact:** Unknown
- **Verdict:** CANDIDATE FOR REMOVAL — validate or kill within 7 days
```

### How to Apply

Every agent entry in your operating manual should answer:

1. **Who consumes this output?** (name the human or agent)
2. **What format do they need?** (not what's convenient to produce)
3. **What breaks if this stops?** (the deletion test)
4. **What's the feedback loop?** (how does the consumer signal quality issues?)

If an agent produces beautiful summaries that nobody reads, it's burning tokens for nothing.

### Anti-Pattern: The "Nice to Have" Agent

```markdown
# BAD: No consumer, no deletion impact
## sentiment-tracker
Monitors social media sentiment about our brand.
Runs daily. Outputs to sentiment-log.md.

# GOOD: Named consumer, clear dependency
## sentiment-tracker
Monitors social media sentiment for weekly-report.
Consumer: weekly-report agent (pulls sentiment delta for executive summary)
Deletion impact: weekly-report loses sentiment section; Sam must manually check socials
Format: JSON with {platform, score_delta, top_mentions[3]}
```

---

## 2. Proof-of-Work Enforcement

**Principle:** Never claim done unless the action actually started. Every status update needs proof — PID, file path, URL, command output. No proof = didn't happen. Write first, speak second.

This pattern exists because LLMs are pathological completers. They want to say "Done!" because that's the satisfying end of a sequence. The problem is they'll say "Done!" before doing anything, or after attempting something that silently failed.

### The Rule

```
STATUS UPDATE FORMAT:
- "Started X" → must include: PID, command, or file path
- "Completed X" → must include: output snippet, file path, or URL
- "Failed X" → must include: error message, what was tried
- "Skipped X" → must include: reason with evidence
```

### Examples

```markdown
# BAD: No proof
✅ Backed up database
✅ Sent daily digest email
✅ Rotated API keys

# GOOD: Every claim has evidence
✅ Backed up database → /backups/2026-03-15-db.sql.gz (43MB, sha256: a1b2c3...)
✅ Sent daily digest → Message-ID: <[email protected]>, 3 recipients
✅ Rotated API keys → new key fingerprint: sk-...x4f2, old key revoked at 14:32 UTC
```

### Implementation Pattern

```bash
# In a script gate or agent wrapper:
run_with_proof() {
  local task="$1"
  shift
  local output
  output=$("$@" 2>&1)
  local exit_code=$?

  if [ $exit_code -eq 0 ]; then
    echo "DONE: $task | proof: $(echo "$output" | tail -3)"
  else
    echo "FAIL: $task | exit=$exit_code | error: $(echo "$output" | tail -5)"
  fi
  return $exit_code
}

# Usage:
run_with_proof "database backup" pg_dump -Fc mydb -f /backups/latest.dump
```

### Agent Operating Manual Rule

```markdown
## Proof-of-Work (AGENTS.md entry)

NEVER say "done" without evidence. For every completed action, include at least one of:
- File path of output produced
- PID of process started
- URL of resource created/modified
- Command output (truncated to last 5 lines)
- Screenshot or hash of artifact

If you cannot produce proof, say "ATTEMPTED but cannot verify" and explain why.
```

---

## 3. Cascading Validation

**Principle:** Dependent sequential steps — each task validates the previous output before starting its own work. Failures loop back with fix instructions, not silent continuations.

Cascading validation prevents the "garbage in, garbage out" problem in multi-step pipelines. Without it, step 3 happily processes the corrupt output of step 2, and you don't discover the problem until step 7.

### The Pattern

```
Step 1: Produce output A
Step 2: Validate A meets spec → if invalid, return to Step 1 with fix instructions
Step 3: Use validated A to produce B
Step 4: Validate B meets spec → if invalid, return to Step 3 with fix instructions
...
```

### Example: Content Pipeline

```markdown
## Newsletter Pipeline (cascading validation)

### Step 1: Research
- Output: research-notes.md
- Validation: must contain ≥ 3 sources, each with URL and date
- Failure: "Research incomplete — need 3+ sourced items. Currently have {n}. Add more."

### Step 2: Draft
- Input: validated research-notes.md
- Pre-check: verify research-notes.md passes Step 1 validation (don't trust upstream)
- Output: draft.md
- Validation: 400-800 words, includes all research items, no placeholder text
- Failure: "Draft {issue}. Fix and resubmit. Do not proceed to editing."

### Step 3: Edit
- Input: validated draft.md
- Pre-check: verify draft.md passes Step 2 validation
- Output: final.md
- Validation: grammar check passes, links resolve, formatting correct
- Failure: "Edit issues found: {list}. Return to editing. Do not publish."

### Step 4: Publish
- Input: validated final.md
- Pre-check: verify final.md passes Step 3 validation
- Gate: HUMAN APPROVAL REQUIRED before publish
```

### Key Rule: Never Trust Upstream

Even if Step 1 "passed," Step 2 should re-validate Step 1's output before proceeding. This catches:
- Race conditions (output modified between steps)
- Silent corruption (file written but content wrong)
- Upstream validation bugs (Step 1's validator had a gap)

### Implementation

```python
def cascading_step(input_path, input_validator, processor, output_validator, max_retries=3):
    """Each step validates its input AND its output."""
    # Validate input (don't trust upstream)
    input_valid, input_errors = input_validator(input_path)
    if not input_valid:
        return {"status": "BLOCKED", "reason": f"Input validation failed: {input_errors}"}

    for attempt in range(max_retries):
        output = processor(input_path)
        output_valid, output_errors = output_validator(output)
        if output_valid:
            return {"status": "DONE", "output": output, "attempts": attempt + 1}
        # Loop back with fix instructions
        processor = make_fix_processor(processor, output_