---

name: architecting-agents description: "Provides industry-proven design patterns for effective AI agents based on production systems like Claude Code, Manus, and Cursor. Use when designing agent architectures, optimizing context management, or implementing sub-agent patterns." user-invocable: true allowed-tools: [Read, Write, Edit, Glob, Grep, Bash]

Architecting Agents Protocol

Architecting Agents Protocol

Provides design patterns for agent context management.

Cost Warning (CRITICAL)

Before using sub-agents, understand the costs:

Default Recommendation: Use context: fork in skills for isolation. Subagents are ONLY appropriate when parallelization benefit clearly exceeds 20K token startup cost AND quota overhead.

See references/subagent-risks.md for detailed evidence.

---

Pattern Index

---

1. Computer Access

Components:

• Filesystem: Persistent context storage, state across sessions
• Shell: Execute utilities, CLIs, scripts, or generated code

Implementation:

CopyAgent → Bash Tool → Shell Utilities / CLIs / Scripts
Agent → File Tools → Read / Write / Edit filesystem

---

2. Multi-Layer Action Space

Action Hierarchy:

CopyLevel 1: Tool Calling (agent-visible)
  ↓
Level 2: Shell Utilities / CLIs (computer-level)
  ↓
Level 3: Code Execution (generated scripts)

---

3. Progressive Disclosure

Strategies:

Implementation Pattern:

Copy1. Provide short list of available capabilities
2. Agent reads detailed spec only when task matches
3. Execute with full knowledge loaded just-in-time

---

4. Context Offloading

Approaches:

• Write old tool results to files
• Store agent trajectories for later retrieval
• Apply summarization only after offloading diminishing returns

Plan File Pattern: Write plan to file → Read periodically to reinforce objectives → Verify work against plan

---

5. Context Caching

Caching Requirements:

• Stable prefix (system prompt unchanged)
• Append-only message history
• Deterministic serialization (sorted JSON keys)

Anti-Pattern: Mutating history in ways that break cache prefix

---

6. Context Isolation

Default Approach: Use context: fork

Copy---
name: processing-batch
description: "Processes multiple files in isolated context"
context: fork
allowed-tools: [Read, Write, Bash]
---

Cost: ~3x inline, but FREE as tool call within prompt quota. Use for: Heavy operations (>10 files), parallel processing, isolation needs.

Subagent Alternatives (Use Sparingly)

ONLY when parallelization benefit > 20K token startup cost:

The Ralph Loop:

Copy1. Initializer sets up environment (plan file, tracking file)
2. Sub-agents tackle individual tasks from plan
3. Progress communicated via git history
4. Stop hooks verify work after each iteration
5. Repeat until plan satisfied

Benefits:

• Prevents single-agent context saturation
• Enables parallel execution
• Clear isolation boundaries

---

7. Context Evolution

Evolution Patterns:

Implementation:

CopySession Log → Reflection → Memory/Skill Update → Context

---

Quick Reference

For detailed implementations, see:

• references/computer-access.md - Filesystem/shell patterns
• references/action-hierarchy.md - Multi-layer tool design
• references/progressive-disclosure.md - Just-in-time context loading
• references/context-patterns.md - Offload, cache, isolate, evolve

Related Skills:

• agent-orchestration - Multi-agent patterns (Orchestrator, Swarm, Hierarchical)
• context-engineering - Compression, degradation, KV-cache optimization
• memory-systems - Long-term memory architectures