architecting-agents_skill

Overview

This skill provides industry-proven design patterns for building robust AI agents focused on context management, isolation, offloading, caching, and evolution. It condenses production practices used in systems like Claude Code, Manus, and Cursor to help you choose efficient architectures and avoid costly anti-patterns. The guidance favours safe defaults and cost-aware use of sub-agents.

How this skill works

The skill prescribes patterns for organizing agent actions, persistent computer access (filesystem and shell), and multi-layer action hierarchies so agents can call tools, run utilities, and execute generated code. It defines progressive disclosure for large capability sets, strategies to offload and cache context to files, and isolation modes (fork vs subagent) with explicit cost trade-offs. Finally, it outlines workflows for evolving context into memories or reusable skills.

When to use it

• Designing agent architectures or choosing how agents manage state and tools
• Optimizing context window usage and reducing prompt costs
• Implementing isolation for batch or parallel processing
• Deciding between inline, fork, or subagent execution strategies
• Building long-running agents that must persist or evolve behavior

Best practices

• Default to context: fork for isolation unless inline suffices; forks balance cost and safety
• Avoid subagents unless parallelization gains clearly exceed high startup token and quota costs
• Use progressive disclosure: list capabilities briefly and load detailed specs only when needed
• Offload older results and trajectories to files; summarize only after evaluating diminishing returns
• Require deterministic serialization and append-only history when implementing caches

Example use cases

• Persistent file-backed agent that reads, writes, and executes scripts to maintain long-term state
• Batch processing pipeline using forked contexts for isolated file transformations across >10 files
• Map-reduce style tasks where forks handle map units and a coordinator reduces results
• Parallel code reviewers where isolation prevents cross-contamination and reviewers write findings to a shared plan file
• Continual learning flow: collect session logs, reflect, distill into memory entries, and update agent instructions