agent-design

# Agent Design

Skill for designing high-performance AI agents following 2025 patterns.

## Documentation

- [patterns.md](docs/patterns.md) - Multi-agent architecture patterns
- [workflows.md](docs/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

```yaml
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)

```markdown
---
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

**K