Writing Agents

Create effective agent definitions that specialize AI behavior for specific tasks. Agents are markdown files with YAML frontmatter that define a subagent's identity, capabilities, and constraints.

Quick Start

Every agent requires a markdown file with YAML frontmatter:

---
name: code-reviewer
description: Reviews code for quality, security, and best practices. Use proactively after code changes.
---

You are a code reviewer. Analyze code for security vulnerabilities, performance issues, and maintainability.

Read the

portable-agents

Core Principles

1. Description Drives Delegation

The

description

# Good - specific triggers, clear scope
description: Reviews code for quality and best practices. Use proactively after code changes.
description: Specialized for multi-repository analysis and finding implementation examples in open source. MUST BE USED when users ask to look up code in remote repositories.

# Bad - vague, no trigger conditions
description: A helpful coding assistant.
description: Does various tasks.

Include "Use proactively" or "MUST BE USED when" to control delegation aggressiveness.

2. System Prompts Are Identity Documents

The markdown body defines who the agent is, what it does, and how it works. Structure it as a complete operating manual, not a suggestion list.

Effective prompts have four layers:

3. Constrain Aggressively

Agents without constraints drift. Every agent should have explicit hard blocks:

## Hard Constraints (NEVER violate)

| Constraint | No Exceptions |
|------------|---------------|
| Type error suppression (`as any`, `@ts-ignore`) | Never |
| Commit without explicit request | Never |
| Speculate about unread code | Never |
| Leave code in broken state | Never |

4. Demand Evidence

Agents that claim completion without proof are unreliable. Require verification artifacts:

## Verification Requirements

Task is NOT complete without:
- `ReadLints` clean on changed files
- Build passes (exit code 0)
- All todos marked completed

**No evidence = not complete.**

Authoring Workflow

Step 1: Define the Role

Answer three questions:

1. What does this agent do? (one sentence)
2. When should the orchestrator delegate to it? (trigger conditions)
3. What should it NOT do? (boundaries)

Step 2: Design the Workflow

Map the agent's process as numbered phases. Each phase should have:

• Entry condition: When to enter this phase
• Actions: What to do
• Exit condition: When to move to next phase

## Phase 0: Intent Gate (EVERY request)

Classify the request type:
| Type | Signal | Action |
|------|--------|--------|
| Trivial | Single file, known location | Direct tools only |
| Exploratory | "How does X work?" | Parallel search |
| Open-ended | "Improve", "Refactor" | Full execution loop |

## Phase 1: Exploration
...

## Phase 2: Execution
...

## Phase 3: Verification
...

Step 3: Write Constraints

Two categories:

Hard blocks (NEVER violate -- use a table for visual weight):

| Constraint | No Exceptions |
|------------|---------------|
| Suppress type errors | Never |
| Commit without request | Never |

Behavioral constraints (agent-specific boundaries):

## Constraints
- **Read-only**: Cannot create, modify, or delete files
- **No delegation**: Cannot spawn other agents
- **No emojis**: Keep output clean and parseable

Step 4: Define Output Contract

Specify exactly what the agent returns. Structured output formats prevent ambiguity:

## Output Contract

Always end with this format:

<results>
<files>
- /absolute/path/file.ts — [why relevant]
</files>
<answer>
[Direct answer to the actual need]
</answer>
</results>

Step 5: Add Communication Style

Prevent AI slop with explicit style rules:

## Communication Style
- Start work immediately. No acknowledgments.
- Don't summarize unless asked.
- One word answers are acceptable.
- Never start with flattery ("Great question!")

Step 6: Deploy

Place the file in the appropriate directory:

.claude/agents/

~/.claude/agents/

.cursor/agents/

~/.cursor/agents/

.opencode/agents/

~/.config/opencode/agents/

For multi-tool deployment, see the

portable-agents

System Prompt Patterns

Intent Gate Pattern

Start every agent with request classification. Prevents the agent from using a sledgehammer on a thumbtack:

## Phase 0: Intent Gate

| Type | Signal | Action |
|------|--------|--------|
| **Trivial** | Single file, direct answer | Direct tools only |
| **Explicit** | Specific file/line, clear command | Execute directly |
| **Exploratory** | "How does X work?" | Parallel search |
| **Open-ended** | "Improve", "Refactor" | Assess → plan → execute |
| **Ambiguous** | Unclear scope | Ask ONE clarifying question |

Parallel-First Pattern

For search/research agents, mandate parallel tool execution:

## Parallel Execution (DEFAULT behavior)

Launch **3+ tools simultaneously** in your first action:

Grep(pattern="auth", path="src/")
Glob(glob_pattern="**/auth*.ts")
SemanticSearch(query="Where is authentication implemented?")

Never sequential unless output depends on prior result.

Todo Obsession Pattern

For execution agents, enforce progress tracking:

## Todo Management (NON-NEGOTIABLE)

- 2+ steps → Create todos FIRST
- Mark `in_progress` before starting (ONE at a time)
- Mark `completed` IMMEDIATELY after each step
- NEVER batch completions

Skipping todos on non-trivial tasks = INCOMPLETE WORK.

Failure Recovery Pattern

Prevent agents from spiraling on broken code:

## Failure Recovery

1. Fix root causes, not symptoms
2. Re-verify after EVERY fix attempt
3. Never shotgun debug

**After 3 consecutive failures:**
1. STOP all edits
2. REVERT to last working state
3. DOCUMENT what failed
4. ASK USER for guidance

Codebase Assessment Pattern

For agents that modify code, assess before following patterns:

## Codebase Assessment

| State | Signals | Behavior |
|-------|---------|----------|
| **Disciplined** | Consistent patterns, configs, tests | Follow existing style |
| **Transitional** | Mixed patterns | Ask which pattern to follow |
| **Legacy/Chaotic** | No consistency | Propose conventions |
| **Greenfield** | New/empty project | Apply modern best practices |

Writing Orchestrator Rules

Orchestrator rules tell the root thread when and how to delegate. They're separate from agent definitions.

Cursor:

.cursor/rules/orchestrator.mdc

---
description: Root-level orchestration brain
alwaysApply: true
---

# Orchestration Rules
[delegation logic]

Claude Code / OpenCode:

AGENTS.md

Put orchestration rules in

AGENTS.md

Key Orchestrator Components

1. Auto-triggers: Signals that fire agents proactively
2. Request classification: Map request types to agent dispatch
3. Phase chaining: Sequential agent handoffs with context passing
4. Verification gates: Evidence requirements between phases
5. Failure recovery: Escalation paths when agents fail

See references/orchestration-patterns.md for complete examples.

Anti-Patterns

Validation Checklist

Before finalizing an agent:

• description

  includes specific trigger conditions
• System prompt has identity, workflow, constraints, and output contract
• Hard constraints table present with "No Exceptions" column
• Verification requirements defined with evidence types
• Communication style section prevents AI slop
• Failure recovery protocol included (for execution agents)
• Tested delegation from orchestrator
• Prompt under 500 lines (move details to references)

References

• references/orchestration-patterns.md - Complete orchestrator rule examples
• references/prompt-templates.md - Starter templates for common agent roles