Agent Architect

Agent Architect Skill

A skill that governs how to design, review, or debug multi-agent systems.

Identify which operation applies, then follow the corresponding section.

---

Operation: DESIGN — Designing an Agent System

Required Input from Previous Phases

If data-scientist (Phase 0) and context-engineer (Phase 0.5) have run, use their output:

• Problem Statement — from data-scientist (what we're solving, who needs it, what success looks like)
• Data Profile — from data-scientist (what data exists, what's signal vs noise)
• Context Spec — from context-engineer (how data loads into context, token budget, loading strategy)

Do not re-discover what Phase 0 already answered. The problem statement IS your starting point — design the agent to solve THAT problem with THAT data.

Pre-Design Checklist

Before proposing any architecture, verify:

• [ ] I have the problem statement from data-scientist (or directly from the user)
• [ ] I have the context spec from context-engineer (if data is involved)
• [ ] I have considered whether a single agent can handle it (start here)
• [ ] I know the tools available or needed
• [ ] I know the input/output contract — what goes in, what comes out
• [ ] I have identified failure modes and how to handle them

If any item is unclear, ask the user before designing.

Rule 1 — Start with One Agent

A single agent with good tools solves most problems. Add agents only when:

• The task has distinct phases requiring different expertise or tool sets
• Context window limits force splitting long workflows
• Parallel execution of independent subtasks provides meaningful speedup
• Safety boundaries require separating privileged from unprivileged operations

If none of these apply, use one agent.

Rule 2 — One Task, One Agent (Critical for Accuracy)

An agent that does one thing does it well. An agent that does many things does all of them poorly.

Splitting responsibilities into single-task agents dramatically improves accuracy because:

• The agent's full context window focuses on one objective
• Tool selection is unambiguous — fewer tools means fewer wrong choices
• Prompts stay short and specific — no competing instructions
• Failures are isolated — one agent failing does not corrupt another's work
• Evaluation is straightforward — test one behavior, not a bundle

Every agent must have:

• One task — describable in a single sentence without "and"
• A defined tool set — only the tools needed for that one task
• Clear input/output contracts — what it receives, what it returns
• No overlap with other agents' responsibilities

Test: If your agent description contains "and" (e.g., "parses logs and generates reports"), split it into two agents.

Before:

Agent: "general helper" — has all tools, handles everything
  Result: mediocre at all tasks, picks wrong tools, bloated context

After:

Agent 1: "code reviewer" — receives a diff, returns structured feedback
  Tools: read_file, grep, run_tests
  Input: { diff: string, context: string }
  Output: { issues: [{severity, file, line, message}], summary: string }

Agent 2: "report generator" — receives review results, produces markdown report
  Tools: write_file, format_markdown
  Input: { issues: [...], summary: string }
  Output: { report_path: string }

Rule 3 — Choose an Orchestration Pattern

| Pattern | When to Use | How It Works | |---|---|---| | Sequential | Ordered pipeline (parse → validate → transform) | Each agent's output feeds the next agent's input | | Parallel | Independent subtasks (lint + test + typecheck) | Run simultaneously, aggregate results | | Hierarchical | Complex task needing delegation | Orchestrator breaks task down, delegates to specialists, synthesizes | | Router | Input determines which specialist to use | Classifier directs to the right agent based on input type |

Prefer deterministic routing (if/else, regex, keyword match) over LLM-based routing when the categories are well-defined. Use LLM routing only when input is ambiguous.

Rule 4 — Design State and Memory

• Use structured formats (JSON objects) for state that agents read/write
• Use unstructured text for progress notes and reasoning traces
• Keep shared state minimal — pass only what the next agent needs
• For long-running tasks, use checkpoints (git commits, file snapshots) so work is not lost on failure

Rule 5 — Define Handoff Protocols

For each handoff between agents, specify:

1. Trigger — what condition causes the handoff
2. Payload — exactly what data transfers (not "everything")
3. Context — minimal background the receiving agent needs
4. Fallback — what happens if the receiving agent fails

Rule 6 — Design for Failure

Every agent system must handle:

• Agent failure — one agent errors or returns garbage → retry with backoff, then escalate
• Loops — agent calls the same tool repeatedly → circuit breaker after N attempts
• Context overflow — input too large → summarize or chunk before passing
• Wrong routing — input goes to the wrong agent → add a catch-all with re-routing logic

Rule 7 — Design for Observability

Log these events at minimum:

• Agent activation (which agent, why, what input)
• Tool calls (which tool, what arguments, what result)
• Handoffs (from which agent, to which agent, what payload)
• Failures (what failed, what fallback was taken)
• Final output (what was returned to the user)

---

Operation: REVIEW — Reviewing an Agent Architecture

Evaluation Dimensions

| Dimension | Score 1 | Score 5 | |---|---|---| | Simplicity | Over-engineered, too many agents | Minimal agents, each clearly justified | | Responsibility clarity | Overlapping or vague roles | Each agent has one sentence job description | | Tool coverage | Missing tools or unnecessary tools | Each agent has exactly the tools it needs | | Error handling | No failure handling | Retries, circuit breakers, fallbacks defined | | State management | Entire context shared everywhere | Minimal, structured state passed explicitly | | Observability | No logging | All decisions, handoffs, and failures logged |

Output Format

## Agent Architecture Review

### Scores
| Dimension              | Score (1-5) | Notes |
|------------------------|-------------|-------|
| Simplicity             |             |       |
| Responsibility clarity |             |       |
| Tool coverage          |             |       |
| Error handling         |             |       |
| State management       |             |       |
| Observability          |             |       |

### Overall Score: X / 30

### Critical Issues
- ...

### Suggestions
- ...

Common Anti-Patterns

• The everything agent — one agent with all tools and no clear role
• Premature multi-agent — using 5 agents where 1 would suffice
• Context dumping — passing entire conversation history between agents instead of a summary
• LLM router for known categories — using an LLM to classify when a regex or keyword match works
• No failure path — no defined behavior when an agent errors
• Circular handoffs — Agent A calls Agent B calls Agent A

---

Operation: DEBUG — Diagnosing Agent Issues

Systematic Diagnosis

When an agent system misbehaves, check in this order:

1. Check routing — Is the right agent receiving the task? Log the routing decision.
2. Check tool definitions — Are tool names, descriptions, and schemas correct? The model reads these to decide which tool to call.
3. Check context size — Is the agent receiving too much or too little context? Measure token count.
4. Check handoff contracts — Is the payload between agents complete? Missing fields cause downstream failures.
5. Check for loops — Is an agent calling the same tool repeatedly? Add a call counter.
6. Check output format — Is the agent returning what the next step expects? Schema mismatches cause silent failures.

Common Failure Modes

| Symptom | Likely Cause | Fix | |---|---|---| | Agent loops on same tool | Tool returns unhelpful result, agent retries | Improve tool error messages, add circuit breaker | | Agent calls non-existent tool | Tool name mismatch or hallucination | Verify tool names match exactly, reduce tool count | | Context overflow errors | Too much state passed between agents | Summarize context, pass only what's needed | | Wrong agent handles task | Router misclassifies input | Add examples to router, use deterministic rules | | Agent produces empty output | Missing required context | Check input contract, ensure all required fields present | | Cascading failures | No error isolation between agents | Add try/catch per agent, define fallback behavior |

---

Post-Design Verification

After designing, reviewing, or debugging, confirm:

• [ ] Each agent has a one-sentence role description
• [ ] No two agents have overlapping responsibilities
• [ ] Tool sets are minimal — no agent has tools it does not need
• [ ] Input/output contracts are explicit for every handoff
• [ ] Failure handling is defined for every agent
• [ ] State passed between agents is minimal and structured
• [ ] The system could be explained to a new team member in under 2 minutes

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ravi2799
• Source: ravi2799/ai-agent-skills
• License: MIT
• Homepage: https://skills.sh

Install and usage instructions live in the source repository linked above.