Subagent prompting

Sub-Agent Prompting Template

Overview

This skill provides a standardized template for invoking sub-agents with deterministic inputs and predictable outputs. Use this when:

• Orchestrating specialist sub-agents (code auditor, test auditor, etc.)
• Designing multi-agent workflows with conditional branching
• Ensuring consistent prompt structure across sub-agent invocations

4-Part Template (Required)

Every sub-agent invocation MUST include all four parts. Incomplete prompts lead to unpredictable behavior.

GOAL (What Success Looks Like)

State the high-level objective, not just the action. Good goals are outcome-focused.

## GOAL

[Describe the desired end state, not the process]

Examples:
- GOOD: "Identify all security vulnerabilities that could allow unauthorized data access"
- BAD: "Review the auth file"

- GOOD: "Refactor authentication module for improved maintainability without breaking existing tests"
- BAD: "Refactor the code"

CONSTRAINTS (What You Cannot Do)

Explicit boundaries prevent scope creep and unexpected changes.

## CONSTRAINTS

- [Hard limit 1: e.g., "Do NOT modify any files"]
- [Hard limit 2: e.g., "Do NOT add new dependencies"]
- [Hard limit 3: e.g., "Maintain backward API compatibility"]
- [Resource limit: e.g., "Complete within 50 tool calls"]

Examples:
- "Identify issues only - do NOT implement fixes"
- "Read-only analysis - no file modifications"
- "Focus only on files in src/auth/ directory"

CONTEXT (What You Need to Know)

Provide all information required to complete the task. Sub-agents run in isolated context and cannot access parent conversation.

## CONTEXT

### Files to Analyze
- `path/to/file1.ts` - [brief description of relevance]
- `path/to/file2.ts` - [brief description of relevance]

### Related Context
- Previous findings: [summary of relevant prior work]
- Architecture notes: [relevant design decisions]
- Known issues: [existing problems to be aware of]

### Standards to Apply
- [Coding standard or guideline reference]
- [Security policy reference if applicable]

OUTPUT (What to Deliver)

Specify concrete deliverables with exact format requirements.

## OUTPUT

### Primary Deliverable
Write findings to: `logs/{agent-name}-{timestamp}.md`

### Output Format
[Specify structure: YAML, Markdown sections, etc.]

### Summary Requirements
Return to main thread: [max 200 tokens summary of key findings]

### Diagnostic Output
Write to: `logs/diagnostics/{agent-name}-{timestamp}.yaml`

---

Pipeline Syntax (F# Conceptual Notation)

Understanding the Notation

F# pipe syntax (|>) is a conceptual notation for planning and documentation. It is NOT directly executable Claude Code syntax.

// This is documentation, not executable code
Agent1 (task) |> Agent2 (task) |> Agent3 (task)

Purpose: Visualize workflow dependencies and conditional logic before implementation.

Mapping to Task() Invocations

Each pipeline stage maps to a sequential Task() call from the main thread:

// Conceptual pipeline
CodeAuditor (security) |> CodeAuditor (architecture) |> (if findings > 0 then IssueDebugger else Done)

Actual execution:

1. Main thread invokes: Task(description="Security audit", subagent_type="sonnet", prompt="[4-part prompt]")
2. Main thread reads log output, extracts findings
3. Main thread invokes: Task(description="Architecture audit", subagent_type="sonnet", prompt="[4-part prompt]")
4. Main thread reads log output, extracts findings
5. IF findings.count > 0: Main thread invokes IssueDebugger
6. ELSE: Pipeline complete

Pipeline Patterns

Code Review Pipeline:

CodeAuditor (security)
|> CodeAuditor (architecture)
|> TestAuditor (coverage)
|> (if findings > 0 then IssueDebugger else Done)

Fix Validation Pipeline:

IssueDebugger (root cause)
|> Implementer (apply fix)
|> CodeAuditor (verify quality)
|> TestAuditor (verify tests)
|> (if issues > 0 then IssueDebugger else Done)  // Loop until clean

Test Audit Pipeline:

TestAuditor (classify all)
|> (if mock_heavy > 0 then VerificationScriptCreator else Done)
|> Implementer (rewrite flagged)
|> TestAuditor (re-verify)

Key Constraint

Sub-agents CANNOT spawn other sub-agents. All pipeline orchestration happens from the main thread.

---

Custom Agent vs Built-in Agent

Agent Selection Priority

Before spawning a pipeline stage:

1. Check .claude/agents/ for a custom agent matching the task
2. If custom agent exists: Use its name field as subagent_type - this invokes the custom agent
3. If no custom agent: Use general-purpose and provide full specialized instructions in the prompt

Important: 4-Part Prompt Always Required

Regardless of agent type, every Task invocation MUST include the 4-part prompt (GOAL/CONSTRAINTS/CONTEXT/OUTPUT) and follow subagent-output-templating for output format.

Built-in Agent Types

Type	Use Case
general-purpose	Multi-step tasks, code writing, analysis
Explore	Fast codebase exploration, file search
Plan	Architecture planning, implementation design
Bash	Command execution

Example: Custom Agent EXISTS

# .claude/agents/security-auditor.md exists with name: security-auditor
Task(
    description="Security audit",
    subagent_type="security-auditor",  # Invokes the custom agent
    prompt="""
## GOAL
Identify security vulnerabilities in calculator.ts

## CONSTRAINTS
- Do NOT modify files

## CONTEXT
File: src/calculator.ts

## OUTPUT
Write to: logs/security-audit-{timestamp}.yaml
"""
)

Example: Custom Agent DOES NOT Exist

# No custom agent for this task - use general-purpose
Task(
    description="Security audit",
    subagent_type="general-purpose",
    model="sonnet",
    prompt="""
## GOAL
Identify security vulnerabilities in calculator.ts using OWASP Top 10 patterns.

## CONSTRAINTS
- Do NOT modify files
- Focus on injection, auth, and data exposure risks

## CONTEXT
File: src/calculator.ts
This is a calculator module with arithmetic operations.

## OUTPUT
Write findings to: logs/security-audit-{timestamp}.yaml
Format: YAML with findings array, severity, and recommendations
"""
)

Note: When no custom agent exists, the prompt must include all specialized instructions that would otherwise be in the custom agent's markdown file.

---

Model Selection Guidance

Task-Type Based Selection (Objective)

Model selection is based on task type, not subjective complexity. This keeps selection deterministic and objective.

Model	Task Type	Examples
Haiku	Lookups & Execution	Web fetch, file read/summarize, collect logs, run tests, typecheck, lint, simple classification
Sonnet	Review & Analysis	Code review, test review, audits, failure analysis, security analysis
Opus	Write & Fix	Write code, write tests, write fixes, apply changes

Selection Rules

1. Determine task type from the action verb:

   • Lookup/Execute/Run/Fetch → Haiku
   • Review/Analyze/Audit/Classify → Sonnet
   • Write/Fix/Implement/Apply → Opus

2. Custom agent override: If a custom sub-agent has agent: in its frontmatter, use that model instead of these rules.

3. Always specify model: Every Task() invocation must include subagent_type.

Pipeline Example

Orchestrator (Opus) writes initial code
     ↓
Sub-agent (Sonnet) reviews → finds issues
     ↓
Sub-agent (Opus) fixes
     ↓
Sub-agent (Sonnet) re-reviews
     ↓
[Loop until clean]

Anti-Patterns

Anti-Pattern	Why It's Wrong	Correct Approach
Using Opus for lookups	Wastes budget on simple tasks	Use Haiku for lookups
Using Haiku for code review	Misses nuanced issues	Use Sonnet for analysis
Using Sonnet for writing fixes	Suboptimal quality	Use Opus for writing
No model specified	Unpredictable behavior	Always specify subagent_type
Ignoring custom agent frontmatter	Overrides intended behavior	Respect agent: field

---

Diagnostic Output (Required)

When this skill is used to invoke a sub-agent, the sub-agent MUST write diagnostic output.

Diagnostic File Location

logs/diagnostics/{skill-name}-{YYYYMMDD-HHMMSS}.yaml

Diagnostic Format

skill: subagent-prompting
timestamp: 2026-01-10T12:30:45Z
diagnostics:
  model_requested: sonnet
  model_actual: sonnet
  context_type: main
  parent_vars_accessible: true
  hooks_fired: []
  execution_time_ms: 1250
  completion_status: success
notes: "Skill invoked successfully"

When to Write Diagnostics

• At the END of skill execution (success or failure)
• Include actual model used (may differ from requested)
• Record execution time for performance tracking

---

Quick Reference

Prompt Checklist

[ ] GOAL: Outcome-focused objective stated
[ ] CONSTRAINTS: Hard limits explicitly listed
[ ] CONTEXT: All required files and background provided
[ ] OUTPUT: Log path, format, and summary requirements specified
[ ] DIAGNOSTIC: logs/diagnostics/ path included

Task() Invocation Template

Task(
    description="[3-5 word summary]",
    subagent_type="sonnet",  # or "haiku", "opus"
    prompt="""
## GOAL
[Outcome-focused objective]

## CONSTRAINTS
- [Limit 1]
- [Limit 2]

## CONTEXT
[Files, background, standards]

## OUTPUT
Write to: logs/{agent}-{timestamp}.md
Diagnostic: logs/diagnostics/{agent}-{timestamp}.yaml
Summary: [max 200 tokens]
"""
)

---

References

For extended examples and edge cases, see references/examples.md.