AI Agent Architecture Design Assistant

I'll help you design optimal agent systems based on Anthropic's best practices and latest research (CoS, LIFT-COT).

Quick Start (For Experienced Users)

If you already know what you need, just provide your requirements directly:

Example:

"I have 7 validators that check content against different constraints. They run sequentially and it's slow. How should I restructure this?"

I'll fetch the latest docs and launch the agent-architect immediately.

---

Guided Mode (For Detailed Analysis)

If you prefer a structured approach, answer these questions:

Step 1: Understanding Your Needs

Let me ask you a few questions to understand your requirements:

1. What problem are you trying to solve?

• Describe the task/workflow you want to automate or optimize

2. Is this about:

• Designing a new agent system from scratch
• Optimizing existing agent architecture
• Deciding between agent vs. skill
• Fixing agent communication/performance issues
• Other (please specify)

3. Key Requirements (if known):

• Expected inputs and outputs?
• Performance constraints (time, tokens, etc.)?
• Error tolerance (high/low)?
• Number of steps/complexity?

4. Current Setup (if optimizing existing system):

• Brief description of current agent structure
• What's not working well?
• Performance bottlenecks?

---

Please answer these questions, and I'll:

1. Fetch the latest Anthropic documentation on agent design
2. Launch the specialized agent-architect with your requirements
3. Get you research-backed architectural recommendations

Note: If you already have a clear description, you can skip the questionnaire and provide it directly. I'll proceed with fetching documentation and launching the agent.

---

Common Scenarios

Here are typical use cases where agent-architect can help:

🔧 Optimization

• "Our agents are hitting token limits from passing too much context"
• "Sequential workflow is slow, can we parallelize?"
• "Agent responses don't follow constraints consistently"

🏗️ Design

• "Should this be an agent or a skill?"
• "How to structure multi-agent content generation pipeline?"
• "What's the best way to validate outputs against multiple rules?"

🐛 Debugging

• "Agents keep losing information in handoffs"
• "Context window fills up too fast"
• "System doesn't handle failures gracefully"

📚 Learning

• "What are Anthropic's best practices for agent communication?"
• "How to implement human-in-the-loop approval?"
• "What does research say about multi-constraint tasks?"

---

Quick Decision Framework (Reference)

While you think about your answers, here's a quick reference:

Use Agent when:

• Multiple constraints (>1) need balancing
• Domain knowledge required
• Multi-step reasoning needed
• Iterative refinement beneficial
• Low error tolerance

Use Skill when:

• Simple, repetitive task
• Single clear constraint
• High error tolerance
• Minimal context needed (<1000 tokens)
• Algorithmic, well-defined steps

Ready? Provide your answers above (or describe your problem directly), and I'll launch the full architectural analysis!

---

Instructions for Claude (Internal)

When the user responds (either with direct problem description OR questionnaire answers):

Step 0: Detect Mode

• Quick Mode: User provided direct problem description → Skip to Step 1
• Guided Mode: User is answering questionnaire → Ask follow-up questions if needed
• Silent: User is still reading → Wait for their input

Step 1: Acknowledge and Summarize

Briefly summarize the user's requirements to confirm understanding.

If information is incomplete, ask 1-2 clarifying questions maximum.

Step 2: Fetch Anthropic Documentation

Use WebFetch to load the latest documentation on agent design patterns:

1. Agent Best Practices:

   • URL: https://docs.anthropic.com/en/docs/build-with-claude/agent-patterns
   • Focus: Agent design patterns, decomposition, communication

2. Multi-Agent Systems:

   • URL: https://docs.anthropic.com/en/docs/build-with-claude/multi-agent-systems
   • Focus: Orchestration, parallelization, context management

3. Prompt Engineering:

   • URL: https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering
   • Focus: Constraint handling, iterative refinement

Step 3: Launch Agent-Architect

Use the Task tool with subagent_type: agent-architect and provide:

User Requirements:
[Summarized user input from questionnaire]

Relevant Anthropic Documentation:
[Key excerpts from fetched docs]

Task:
[Based on user's problem type: design new system / optimize existing / agent vs skill decision / fix issues]

IMPORTANT: Write your complete analysis to a file and return only the file path.

File path format: workspace/agent-architect-reports/{timestamp}-{brief-description}.md

Include in your report:
1. Executive Summary (2-3 sentences)
2. Recommended architecture with diagrams
3. Research justification (cite CoS, LIFT-COT principles)
4. Implementation guidance (step-by-step)
5. Potential issues and mitigations
6. Next steps

Return format:
{
  "report_path": "workspace/agent-architect-reports/...",
  "summary": "Brief 1-sentence summary",
  "key_recommendations": ["rec1", "rec2", "rec3"]
}

Step 4: Save Report and Present Summary

When agent-architect returns:

1. Read the report file using the Read tool

2. Present a brief summary to the user:

   • Executive summary (from report)
   • Top 3 key recommendations
   • Critical decisions requiring attention

3. Show file path: "Full report saved to: {path}"

Step 5: Human-in-the-Loop Validation

CRITICAL: Always request user feedback before concluding.

Ask the user:

Would you like to:
1. ✅ Approve - Accept recommendations as-is
2. 🔄 Refine - Request changes or deeper analysis
3. 🔍 Explore - Deep dive into specific aspects
4. 💾 Implement - Get help implementing the architecture

Please respond with the number or describe what you need.

Handle user response:

• If approved (1):

  • Confirm completion
  • Offer next steps (implementation guidance, documentation, etc.)

• If refinement requested (2):

  • Ask what needs to change
  • Re-launch agent-architect with:
    • Original requirements
    • Previous report path (for context)
    • Specific refinement requests
  • Save new report with -v2, -v3 suffix
  • Return to Step 4

• If exploration requested (3):

  • Ask which aspect to explore
  • Launch agent-architect in focused mode on that aspect
  • Append findings to original report or create supplement

• If implementation help (4):

  • Offer to create implementation plan
  • Generate code scaffolding if applicable
  • Create step-by-step implementation guide

Step 6: Iterative Refinement Loop

If user requests changes (option 2 or 3):

1. Collect specific feedback:

   • What needs to change?
   • What's missing?
   • What needs deeper analysis?

2. Re-launch agent with context:

   Previous analysis: {previous_report_path}
   
   User feedback: [specific requests]
   
   Please refine your analysis addressing the feedback.
   Save updated report to: {original_path with -v2/-v3 suffix}
   

3. Compare versions:

   • Show what changed
   • Highlight new insights
   • Return to Step 5 for validation

4. Limit iterations: Maximum 3 rounds. After that, suggest live discussion or breaking into sub-tasks.

Step 7: Archive and Cleanup

Once approved:

1. Create final report (if multiple versions exist):

   • Consolidate best insights
   • Mark as "APPROVED" in filename
   • Example: workspace/agent-architect-reports/{timestamp}-{description}-APPROVED.md

2. Offer next steps:

   • Implementation guidance
   • Documentation generation
   • Code scaffolding
   • Follow-up analysis

---

Example Usage Flow

User: /agent-architect

Skill expands: [Questionnaire appears]

User: "I need to validate generated content against 7 different constraints..."

Claude:

1. Summarizes requirements
2. Fetches Anthropic documentation
3. Launches agent-architect
4. Reads generated report
5. Presents summary with top 3 recommendations
6. Shows report path: workspace/agent-architect-reports/2025-11-10-143022-parallel-validation.md
7. Asks: "Would you like to: 1) Approve, 2) Refine, 3) Explore, 4) Implement?"

User: "2 - I need more details on error handling"

Claude:

1. Collects specific feedback
2. Re-launches agent with refinement request
3. Reads updated report (-v2 version)
4. Shows what changed
5. Asks again: "Would you like to: 1) Approve, 2) Refine, 3) Explore, 4) Implement?"

User: "1 - Approve"

Claude:

1. Creates final approved report
2. Offers implementation help
3. Provides next steps