diegosouzapw Agent Design
Skill for designing high-performance AI agents following 2025 patterns.
Documentation
- patterns.md - Multi-agent architecture patterns
- workflows.md - Recommended workflows
Fundamental Distinction
Workflows vs Agents
| Type | Control | When to use |
|---|---|---|
| Workflow | Code orchestrates LLM | Predictable tasks, need for control |
| Agent | LLM directs its actions | Flexibility, adaptive decisions |
Golden rule: Start simple, add complexity if necessary.
Agent Architecture
Minimal Structure
Agent:
identity: Who am I?
capabilities: What can I do?
tools: What tools do I have?
constraints: What are my limits?
workflow: How should I proceed?
Complete Structure (Production)
---
name: my-agent
description: Short description
model: sonnet|opus
tools: [list of tools]
skills: [associated skills]
---
# Identity
[Who the agent is]
# Capabilities
[What it can do]
# Workflow
[Steps to follow]
# Tools
[How to use each tool]
# Constraints
[Limits and rules]
# Examples
[Use cases]
# Forbidden
[What it must NEVER do]
Agent Patterns
1. Single Agent (Simple)
User → Agent → Response
Usage: Simple tasks, rapid prototyping.
2. Agent + Tools
User → Agent ↔ Tools → Response
↑
Tool Results
Usage: Tasks requiring external access (API, files, DB).
3. Orchestrator + Subagents
User → Orchestrator → Subagent 1 (specialized)
→ Subagent 2 (specialized)
→ Subagent 3 (specialized)
↓
Synthesis → Response
Usage: Complex tasks, separation of responsibilities.
4. Sequential Pipeline
User → Agent 1 → Agent 2 → Agent 3 → Response
(Analyze) (Plan) (Execute)
Usage: Linear processes (e.g., Analyst → Architect → Developer).
Fresh Eyes Principle
Key 2025 concept: Each sub-agent must have a "fresh" context.
❌ Bad: Pass entire history to each sub-agent
✅ Good: Give only necessary information
Orchestrator:
- Keeps complete history
- Extracts relevant context for each sub-agent
- Synthesizes results
Design Checklist
Before creating an agent
- Is the objective clear?
- Would a simple workflow suffice?
- What tools are needed?
- What guardrails are required?
During design
- Is identity well defined?
- Is workflow explicit?
- Are error cases handled?
- Are examples relevant?
After creation
- Standard case tests?
- Edge case tests?
- Security tests (jailbreak)?
- Acceptable performance?
Claude Code Agent Template
---
name: [kebab-case-name]
description: [1-2 lines max]
model: sonnet
color: blue
tools: Read, Edit, Write, Bash, Grep, Glob
skills: [associated-skills]
---
# [Agent Name]
[Purpose description]
## Core Principles
1. **[Principle 1]**: [Short explanation]
2. **[Principle 2]**: [Short explanation]
## Workflow (MANDATORY)
### Phase 1: [Name]
[Numbered actions]
### Phase 2: [Name]
[Numbered actions]
## Output Format
[Response structure]
## Forbidden
- [Prohibition 1]
- [Prohibition 2]
Anti-Patterns to Avoid
❌ Omniscient agent
You know everything and can do anything.
✅ Specialized agent
You are an expert in [specific domain].
For topics outside your domain, redirect to the appropriate agent.
❌ Implicit instructions
Do what's logical.
✅ Explicit instructions
Step 1: Analyze the problem
Step 2: Propose 3 solutions
Step 3: Recommend the best with justification
❌ No error handling
Execute the task.
✅ Explicit error handling
IF the task fails:
1. Identify the cause
2. Propose an alternative
3. Ask for confirmation before retrying
Forbidden
- Never create an agent without explicit workflow
- Never give access to all tools without necessity
- Never ignore the principle of least privilege
- Never forget security guardrails