agent-designer

# Agent Designer — Multi-Agent System Architecture

Design, schema-generate, and evaluate multi-agent systems with three deterministic tools. The scripts are the workflow — do not freehand an architecture when the planner can score one from requirements.

## When to use

- Designing a new multi-agent system from requirements (pattern choice, roles, comms)
- Generating provider-ready tool schemas (Anthropic + OpenAI formats) from plain tool descriptions
- Evaluating execution logs: success rate, latency distribution, cost, bottlenecks

**When NOT to use:** Claude Code Workflow-tool automations → `workflow-builder`; single-agent workflow scaffolds → `agent-workflow-designer`; multi-agent fan-out at runtime → `agenthub`.

## Pattern decision table

| Choose | When | Watch out for |
|---|---|---|
| Single agent | One bounded task, < ~5 tools | Don't add agents you don't need |
| Supervisor | Central decomposition, specialists report back | Supervisor becomes the bottleneck |
| Pipeline | Strictly sequential stages with handoffs | Rigid order; slowest stage gates throughput |
| Hierarchical | Multiple org layers, > ~8 agents | Communication overhead per level |
| Swarm | Parallel peers, fault tolerance over predictability | Hard to debug; needs consensus rules |

The planner applies this scoring deterministically — run it rather than picking by feel.

## Workflow

All paths relative to this skill folder. Each step's JSON output is the next step's design input.

### 1. Design the architecture

Write a requirements JSON (copy `assets/sample_system_requirements.json` — keys: `goal`, `tasks[]`, `constraints{max_response_time, budget_per_task, concurrent_tasks}`, `team_size`):

```bash
python3 agent_planner.py requirements.json --format json -o arch
```

Emits `arch.json` with `architecture_design` (pattern, agents, communication links), `mermaid_diagram`, and `implementation_roadmap`. Read `architecture_design.pattern` and the per-agent role list; present the mermaid diagram to the user.

### 2. Generate tool schemas

Describe each agent's tools in plain JSON (copy `assets/sample_tool_descriptions.json`), then:

```bash
python3 tool_schema_generator.py tool_descriptions.json --validate -o tools
```

Emits `tools.json` (`tool_schemas`, `validation_summary`) plus provider-specific `tools_anthropic.json` / `tools_openai.json`. **Gate: every tool must print `✓ Valid`.** Fix any invalid schema before proceeding — never hand an agent an unvalidated schema.

### 3. Evaluate execution logs

Once the system runs (or against `assets/sample_execution_logs.json` for a dry run):

```bash
python3 agent_evaluator.py execution_logs.json --detailed -o eval
```

Emits `eval.json` with `summary`, `agent_metrics`, `bottleneck_analysis`, `error_analysis`, `cost_breakdown`, `sla_compliance`, and `optimization_recommendations`, plus split files (`eval_errors.json`, `eval_recommendations.json`).

### 4. Verification loop

The design is not done until:

1. `tool_schema_generator.py --validate` reports 0 invalid schemas.
2. `agent_evaluator.py` on a pilot run reports **0 critical issues** (the tool prints `CRITICAL: N critical issues` when found). If N > 0, apply the top item in `eval_recommendations.json`, re-run the pilot, and re-evaluate.
3. Compare your outputs against `expected_outputs/` to confirm the schema shape you're consuming hasn't drifted.

## References

- `references/agent_architecture_patterns.md` — pattern trade-offs in depth
- `references/tool_design_best_practices.md` — schema, idempotency, error-handling rules
- `references/evaluation_methodology.md` — metric definitions the evaluator implements

{
  "format": "aiskill/v1",
  "skill": {
    "name": "agent-designer",
    "slug": "agent-designer",
    "version": "1.0.0",
    "description": "Use when the user asks to design a multi-agent system, pick an orchestration pattern (supervisor/swarm/pipeline), generate tool schemas for agents, or evaluate agent execution logs for cost, latency, and failure bottlenecks. Examples: 'design an agent architecture for research automation', 'generate Anthropic tool schemas from these tool descriptions', 'analyze these agent run logs for bottlenecks'. NOT for Claude Code workflow files (use workflow-builder) or single-agent prompt design (use agent-workflow-designer).",
    "category": "Development",
    "tags": [
      "ai-agents",
      "agents",
      "research",
      "automation"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Agent Designer — Multi-Agent System Architecture\r\n\r\nDesign, schema-generate, and evaluate multi-agent systems with three deterministic tools. The scripts are the workflow — do not freehand an architecture when the planner can score one from requirements.\r\n\r\n## When to use\r\n\r\n- Designing a new multi-agent system from requirements (pattern choice, roles, comms)\r\n- Generating provider-ready tool schemas (Anthropic + OpenAI formats) from plain tool descriptions\r\n- Evaluating execution logs: success rate, latency distribution, cost, bottlenecks\r\n\r\n**When NOT to use:** Claude Code Workflow-tool automations → `workflow-builder`; single-agent workflow scaffolds → `agent-workflow-designer`; multi-agent fan-out at runtime → `agenthub`.\r\n\r\n## Pattern decision table\r\n\r\n| Choose | When | Watch out for |\r\n|---|---|---|\r\n| Single agent | One bounded task, < ~5 tools | Don't add agents you don't need |\r\n| Supervisor | Central decomposition, specialists report back | Supervisor becomes the bottleneck |\r\n| Pipeline | Strictly sequential stages with handoffs | Rigid order; slowest stage gates throughput |\r\n| Hierarchical | Multiple org layers, > ~8 agents | Communication overhead per level |\r\n| Swarm | Parallel peers, fault tolerance over predictability | Hard to debug; needs consensus rules |\r\n\r\nThe planner applies this scoring deterministically — run it rather than picking by feel.\r\n\r\n## Workflow\r\n\r\nAll paths relative to this skill folder. Each step's JSON output is the next step's design input.\r\n\r\n### 1. Design the architecture\r\n\r\nWrite a requirements JSON (copy `assets/sample_system_requirements.json` — keys: `goal`, `tasks[]`, `constraints{max_response_time, budget_per_task, concurrent_tasks}`, `team_size`):\r\n\r\n```bash\r\npython3 agent_planner.py requirements.json --format json -o arch\r\n```\r\n\r\nEmits `arch.json` with `architecture_design` (pattern, agents, communication links), `mermaid_diagram`, and `implementation_roadmap`. Read `architecture_design.pattern` and the per-agent role list; present the mermaid diagram to the user.\r\n\r\n### 2. Generate tool schemas\r\n\r\nDescribe each agent's tools in plain JSON (copy `assets/sample_tool_descriptions.json`), then:\r\n\r\n```bash\r\npython3 tool_schema_generator.py tool_descriptions.json --validate -o tools\r\n```\r\n\r\nEmits `tools.json` (`tool_schemas`, `validation_summary`) plus provider-specific `tools_anthropic.json` / `tools_openai.json`. **Gate: every tool must print `✓ Valid`.** Fix any invalid schema before proceeding — never hand an agent an unvalidated schema.\r\n\r\n### 3. Evaluate execution logs\r\n\r\nOnce the system runs (or against `assets/sample_execution_logs.json` for a dry run):\r\n\r\n```bash\r\npython3 agent_evaluator.py execution_logs.json --detailed -o eval\r\n```\r\n\r\nEmits `eval.json` with `summary`, `agent_metrics`, `bottleneck_analysis`, `error_analysis`, `cost_breakdown`, `sla_compliance`, and `optimization_recommendations`, plus split files (`eval_errors.json`, `eval_recommendations.json`).\r\n\r\n### 4. Verification loop\r\n\r\nThe design is not done until:\r\n\r\n1. `tool_schema_generator.py --validate` reports 0 invalid schemas.\r\n2. `agent_evaluator.py` on a pilot run reports **0 critical issues** (the tool prints `CRITICAL: N critical issues` when found). If N > 0, apply the top item in `eval_recommendations.json`, re-run the pilot, and re-evaluate.\r\n3. Compare your outputs against `expected_outputs/` to confirm the schema shape you're consuming hasn't drifted.\r\n\r\n## References\r\n\r\n- `references/agent_architecture_patterns.md` — pattern trade-offs in depth\r\n- `references/tool_design_best_practices.md` — schema, idempotency, error-handling rules\r\n- `references/evaluation_methodology.md` — metric definitions the evaluator implements",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The agent-designer/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/agent-designer",
    "exported_at": "2026-11-03T06:35:13.391Z"
  }
}

format: aiskill/v1
skill:
  name: agent-designer
  slug: agent-designer
  version: 1.0.0
  description: >-
    Use when the user asks to design a multi-agent system, pick an orchestration pattern
    (supervisor/swarm/pipeline), generate tool schemas for agents, or evaluate agent execution logs
    for cost, latency, and failure bottlenecks. Examples: 'design an agent architecture for research
    automation', 'generate Anthropic tool schemas from these tool descriptions', 'analyze these
    agent run logs for bottlenecks'. NOT for Claude Code workflow files (use workflow-builder) or
    single-agent prompt design (use agent-workflow-designer).
  category: Development
  tags:
    - ai-agents
    - agents
    - research
    - automation
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Agent Designer — Multi-Agent System Architecture\r\n\r\nDesign, schema-generate, and evaluate multi-agent systems with three deterministic tools. The scripts are the workflow — do not freehand an architecture when the planner can score one from requirements.\r\n\r\n## When to use\r\n\r\n- Designing a new multi-agent system from requirements (pattern choice, roles, comms)\r\n- Generating provider-ready tool schemas (Anthropic + OpenAI formats) from plain tool descriptions\r\n- Evaluating execution logs: success rate, latency distribution, cost, bottlenecks\r\n\r\n**When NOT to use:** Claude Code Workflow-tool automations → `workflow-builder`; single-agent workflow scaffolds → `agent-workflow-designer`; multi-agent fan-out at runtime → `agenthub`.\r\n\r\n## Pattern decision table\r\n\r\n| Choose | When | Watch out for |\r\n|---|---|---|\r\n| Single agent | One bounded task, < ~5 tools | Don't add agents you don't need |\r\n| Supervisor | Central decomposition, specialists report back | Supervisor becomes the bottleneck |\r\n| Pipeline | Strictly sequential stages with handoffs | Rigid order; slowest stage gates throughput |\r\n| Hierarchical | Multiple org layers, > ~8 agents | Communication overhead per level |\r\n| Swarm | Parallel peers, fault tolerance over predictability | Hard to debug; needs consensus rules |\r\n\r\nThe planner applies this scoring deterministically — run it rather than picking by feel.\r\n\r\n## Workflow\r\n\r\nAll paths relative to this skill folder. Each step's JSON output is the next step's design input.\r\n\r\n### 1. Design the architecture\r\n\r\nWrite a requirements JSON (copy `assets/sample_system_requirements.json` — keys: `goal`, `tasks[]`, `constraints{max_response_time, budget_per_task, concurrent_tasks}`, `team_size`):\r\n\r\n```bash\r\npython3 agent_planner.py requirements.json --format json -o arch\r\n```\r\n\r\nEmits `arch.json` with `architecture_design` (pattern, agents, communication links), `mermaid_diagram`, and `implementation_roadmap`. Read `architecture_design.pattern` and the per-agent role list; present the mermaid diagram to the user.\r\n\r\n### 2. Generate tool schemas\r\n\r\nDescribe each agent's tools in plain JSON (copy `assets/sample_tool_descriptions.json`), then:\r\n\r\n```bash\r\npython3 tool_schema_generator.py tool_descriptions.json --validate -o tools\r\n```\r\n\r\nEmits `tools.json` (`tool_schemas`, `validation_summary`) plus provider-specific `tools_anthropic.json` / `tools_openai.json`. **Gate: every tool must print `✓ Valid`.** Fix any invalid schema before proceeding — never hand an agent an unvalidated schema.\r\n\r\n### 3. Evaluate execution logs\r\n\r\nOnce the system runs (or against `assets/sample_execution_logs.json` for a dry run):\r\n\r\n```bash\r\npython3 agent_evaluator.py execution_logs.json --detailed -o eval\r\n```\r\n\r\nEmits `eval.json` with `summary`, `agent_metrics`, `bottleneck_analysis`, `error_analysis`, `cost_breakdown`, `sla_compliance`, and `optimization_recommendations`, plus split files (`eval_errors.json`, `eval_recommendations.json`).\r\n\r\n### 4. Verification loop\r\n\r\nThe design is not done until:\r\n\r\n1. `tool_schema_generator.py --validate` reports 0 invalid schemas.\r\n2. `agent_evaluator.py` on a pilot run reports **0 critical issues** (the tool prints `CRITICAL: N critical issues` when found). If N > 0, apply the top item in `eval_recommendations.json`, re-run the pilot, and re-evaluate.\r\n3. Compare your outputs against `expected_outputs/` to confirm the schema shape you're consuming hasn't drifted.\r\n\r\n## References\r\n\r\n- `references/agent_architecture_patterns.md` — pattern trade-offs in depth\r\n- `references/tool_design_best_practices.md` — schema, idempotency, error-handling rules\r\n- `references/evaluation_methodology.md` — metric definitions the evaluator implements"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The agent-designer/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/agent-designer
  exported_at: "2026-11-03T06:35:13.391Z"