agent-prompt-engineering

name	agent-prompt-engineering
description	Techniques for writing comprehensive, self-contained prompts when spawning sub-agents or teammates via the Task tool. Use when delegating work to agents, designing multi-agent workflows, or when spawned agents are returning poor results due to insufficient context. Covers frontloading, file path enumeration, deliverable specification, constraint injection, and pattern reuse across spawn calls.

Agent Prompt Engineering

How to write prompts that let spawned agents work autonomously without follow-up.

Core Principle

A spawned agent has no memory of your conversation. Everything it needs must be in the prompt. The goal is zero round-trips -- the agent reads the prompt, does the work, and returns a complete result.

The Five Components

Every agent spawn prompt should contain these sections, in this order:

1. Role and Scope

One sentence stating what the agent IS and what it is NOT responsible for.

You are the Brand Architect for [project]. Your job is to create the brand
identity skill and visual guidelines. You are NOT writing the README or
creating demos -- other agents handle those.

Why: Prevents scope creep. Agents with unclear boundaries will attempt everything.

2. File Paths to Read (exhaustive)

List every file the agent needs, with absolute paths. Group by purpose.

## READ THESE FIRST

**Brand resources:**
- ~/.claude/skills/brand-guidelines/SKILL.md
- ~/.claude/skills/brand-guidelines/references/tone-guide.md

**Source code (for technical accuracy):**
- /path/to/project/src/main.sh
- /path/to/project/config.json

**Current state (your starting point):**
- /path/to/project/README.md

Why: Agents cannot guess file locations. Missing a single path means missing context. Absolute paths eliminate ambiguity.

3. Deliverables with Exact Output Paths

Numbered list. Each deliverable has a file path and acceptance criteria.

YOUR DELIVERABLES (in order):

1. CREATE the brand skill at ~/.claude/skills/project-brand/
   Requirements:
   - Color palette with hex codes
   - Tone of voice guidelines with do/don't examples
   - README template

2. WRITE the social preview concept to /path/to/project/docs/social-preview.md
   Requirements:
   - 1280x640 dimensions
   - Exact color specs

Why: "Create a brand guide" is vague. "Create SKILL.md at this path with these sections" is unambiguous. The agent knows exactly what to produce and where to put it.

4. Constraints (non-negotiable rules)

Labeled as CRITICAL. Repeated if they are easy to violate.

CRITICAL CONSTRAINTS:
- NO EMOJIS anywhere. This is absolute.
- All content must be technically accurate -- read the source code.
- Dark-mode optimized -- test all colors against #1a1a2e background.

Why: Agents optimize for completion. Without explicit constraints, they will take shortcuts. Labeling constraints as CRITICAL increases compliance. Repeating important constraints in multiple sections (role, deliverables, constraints) provides redundancy.

5. Communication Protocol

How the agent should report back.

After completing all deliverables, send a message to the team lead
summarizing what you created and where the files are located.

Or for background agents:

Commit your work when done.

Why: Without this, agents may finish silently or produce output in unexpected formats.

Techniques

Frontloading

Put the most important context first. If the agent hits a token limit or loses focus, the critical information was already processed.

Order: Role > Context > File paths > Deliverables > Constraints

Pattern Reuse

When spawning multiple agents in a session, establish a template with the first spawn and adapt it for subsequent ones. Consistent structure across spawns means:

• You write faster (copy-adapt, not write-from-scratch)
• Agents produce consistent output formats
• Review is easier (you know where to look)

Dependency Declaration

When an agent's work depends on another agent's output, state it explicitly:

BEFORE YOU START:
- Read the brand skill at ~/.claude/skills/project-brand/SKILL.md
  (created by the brand-architect agent in Phase 1)
- If this file does not exist, STOP and report the dependency failure.

Context Bridging

Spawned agents cannot see your conversation. When referencing decisions made earlier in the session, include the decision and its rationale:

The team decided on a cyan/amber/red color palette derived from the
project's existing TUI output. These are not arbitrary choices -- they
match the ANSI colors already used in the codebase.

Don't say "use the colors we discussed" -- the agent wasn't there.

Constraint Repetition

For rules that are easy to violate (no emojis, no marketing speak, technical accuracy), state them:

1. In the role section ("you are a technically precise writer who never uses emojis")
2. In the deliverables section ("ensure no emojis in any output")
3. In the constraints section ("CRITICAL: NO EMOJIS")

Three mentions is not redundant -- it is insurance.

File Path Enumeration vs. Discovery

Prefer giving explicit paths over asking the agent to find files:

# Good: agent reads immediately
Read ~/.claude/skills/brand-guidelines/SKILL.md

# Bad: agent wastes turns searching
Find and read the brand guidelines skill

Exception: when the agent's job IS discovery (e.g., "scan ~/.claude/agents/ and report what exists").

Output Path Specification

Always specify where the agent should write. Never let it choose:

# Good: predictable output location
Write to: /path/to/project/docs/launch-content/hacker-news.md

# Bad: agent picks a location you don't expect
Write the HN draft somewhere appropriate

Anti-Patterns

Anti-Pattern	Problem	Fix
"Do what the previous agent did"	Agent has no memory of previous agents	Include the relevant output or file paths
Vague deliverables ("improve the README")	Agent has no acceptance criteria	Specify exactly what to change and why
Missing file paths	Agent guesses or searches, wasting turns	Enumerate every file it needs
No constraints section	Agent takes shortcuts	Add explicit CRITICAL CONSTRAINTS
Overloading one agent	Agent loses focus after 5+ deliverables	Split into multiple agents with 2-3 deliverables each
"Be creative" without boundaries	Unpredictable output	Provide examples of what good output looks like

Scaling: When to Split Agents

• 1-3 deliverables: Single agent
• 4-6 deliverables: Consider splitting if deliverables are in different domains
• 7+ deliverables: Always split. No agent maintains quality across 7+ tasks.

Model Selection

• opus: Creative work (brand identity, copywriting, architecture decisions), complex reasoning
• sonnet: Structured execution (applying a template, reformatting, review checklists)
• haiku: Simple lookups, file scanning, status checks