Agent Design Patterns

Creation Phases

Phase 1: Core Purpose (Required)

Ask these first — they shape everything else:

1. "What should this agent do?" — Get the core task/domain
2. "What should trigger this agent?" — Specific phrases, contexts, file types → becomes description
3. "What expertise/persona should it have?" — Tone, boundaries, specialization → shapes system prompt

Phase 1.5: Research the Domain

MUST NOT assume knowledge is current. After understanding the broad strokes:

• Search for current best practices in the domain
• Check for updates to frameworks, tools, or APIs the agent will work with
• Look up documentation for any unfamiliar technologies mentioned
• Find examples of how experts approach similar tasks

Example: User wants an agent for "Next.js deployments" → Research current deployment patterns, Vercel vs self-hosted, App Router vs Pages Router, common pitfalls, etc.

Phase 2: Capabilities

1. "What permissions does this agent need?"

   • Standard: Omit permission block entirely — rely on system defaults
   • Read-Only: Explicitly deny write, edit, bash
   • Full Access: Allow bash: "*" only if needed
   • Custom: Ask follow-ups

2. "Should this agent use any skills?"

   • If yes: ALWAYS configure permission.skill with "*": "deny" and explicit allows

3. "Is this a subagent?"

   • If yes: set mode: subagent
   • If no: omit mode (defaults to all) or set mode: primary for main-list only

Phase 3: Details (Optional — user MAY skip)

• Specific model preference
• Custom temperature/sampling
• Maximum steps before stopping

Phase 4: Review & Refine

1. Show the draft config and prompt, ask for feedback
2. Iterate until user is satisfied

Key principle: Start broad, get specific only where the user shows interest. Be flexible: If the user provides lots of info upfront, skip phases that are already answered.

Permission Configuration

CRITICAL: Avoid Overengineering

• Do NOT list permissions for standard tools (read, write, edit, bash) unless the user requests restrictions or non-standard access
• Rely on system defaults for most agents
• Skills are the exception: ALWAYS configure permission.skill to whitelist specific skills

# Standard Agent (minimal config)
permission:
  skill:
    "*": "deny"
    "my-skill": "allow"

# Restricted Agent (explicit config)
permission:
  edit: "ask"
  bash:
    "*": "deny"
  skill:
    "*": "deny"

Agent Locations

Common Agent Patterns

Use these as starting points. Each maps a common use case to the right configuration choices.

Read-Only Analyst

Use when the agent should inspect code but NEVER modify files:

---
description: Code quality analyst. Use when user says "review", "analyze", "check my code".
mode: all
permission:
  edit: "deny"
  bash: "deny"
---
You analyze code for quality, security, and performance issues.
You NEVER modify files directly. Provide specific, actionable findings.

Background Subagent

Use for specialized tasks invoked by other agents via the Task tool:

---
description: Test runner specialist. Use for parallel test execution during CI workflows.
mode: subagent
permission:
  bash:
    "*": "ask"
    "npm test": "allow"
    "npx jest": "allow"
  skill:
    "*": "deny"
---
You run test suites and report results. Focus on speed and clear failure summaries.

Skill-Gated Expert

Use when the agent should only access specific skills:

---
description: |-
  Database migration expert. Use when user says "write migration", "alter table",
  "create schema", "database change".
  Examples:
  - user: "add column" -> generate migration
  - user: "index performance" -> suggest index migration
permission:
  skill:
    "*": "deny"
    "supabase-postgres-best-practices": "allow"
    "conventional-commits": "allow"
---
You design safe, reversible database migrations following best practices.

Deployment Gatekeeper

Use when the agent must run shell commands but only specific, safe ones:

---
description: |-
  Deployment helper. Use when user says "deploy to staging", "push to prod", "release".
  Examples:
  - user: "deploy" -> run deployment pipeline
  - user: "rollback" -> revert last deployment
mode: subagent
permission:
  bash:
    "*": "deny"
    "git tag *": "allow"
    "npm run build": "allow"
    "npm run deploy:staging": "allow"
    "npm run deploy:production": "ask"
  skill:
    "*": "deny"
---
You handle deployments safely. Always confirm before production deploys.

Prompt Engineering

Recommended System Prompt Structure

# Role and Objective
[Agent purpose and scope]

# Instructions
- Core behavioral rules
- What to always/never do

## Sub-instructions (optional)
More detailed guidance for specific areas.

# Workflow
1. First, [step]
2. Then, [step]
3. Finally, [step]

# Output Format
Specify exact format expected.

# Examples (optional)
<examples>
<example>
<input>User request</input>
<output>Expected response</output>
</example>
</examples>

XML Tags (Recommended)

XML tags improve clarity and parseability across all models:

<instructions>
1. Analyze the code in <code> tags
2. List issues in <findings> tags
3. Suggest fixes in <recommendations> tags
</instructions>

Description Field (Critical)

The description determines when the agent triggers.

• Primary Agents: Keep extremely concise (3 words max). User selects manually.
• Any Other Agents: Must be specific and exhaustive for correct routing.

Template: [Role/Action]. Use when [triggers]. Examples: - user: "trigger" -> action

Prompt Altitude

Find the balance between too rigid and too vague:

Agentic Reminders

For agents that use tools in a loop, SHOULD include:

# Tool Usage
If unsure about something, use tools to gather information.
Do NOT guess or make up answers.

# Planning (optional)
Think step-by-step before each action. Reflect on results before proceeding.

Single-Agent Patterns

Multi-Agent Patterns

Enhancement & Troubleshooting

1. "What's not working well?" — Get specific symptoms
2. "Can you show me an example where it failed?" — Understand the gap
3. "What should it have done instead?" — Define success

Then propose targeted fixes:

MUST show proposed changes and ask for confirmation before applying.

Quality Checklist

Before showing the final agent to the user:

• Asked about core purpose and triggers
• Researched the domain (MUST NOT assume knowledge is current)
• description has concrete trigger examples
• mode discussed and set appropriately
• System prompt uses second person
• Asked about tool/permission needs (MUST NOT assume)
• Output format is specified if relevant
• Showed draft to user and got feedback
• User confirmed they're happy with result

Legacy Configuration

Agents may occasionally use outdated frontmatter (e.g., tools:, maxSteps:). Correct these to modern permission: and steps: fields when encountered.