agent-designlisted

# Agent Design Skill ## Core Principles Three axioms everything else derives from: 1. **Tools are primitive system boundaries.** They expose raw capabilities without encoding usage assumptions. 2. **Skills are usage knowledge.** They teach the agent when and how to wield those primitives—as knowledge, workflows, CLI wrappers, delegation patterns, or tool integration guides. 3. **The context window is real state.** Everything else is a projection. ## Quick Decision Rules **Tool or Skill?** - New system boundary (shell, filesystem, web, external API) → **Tool** - Teaching the agent to use an existing capability reliably → **Skill** - See [decision-tree.md](./references/decision-tree.md) for full breakdown **Workflow or Agent loop?** - Subtasks are predictable and fixed-order → **Workflow** - Path depends on prior results and can't be hardcoded → **Agent** **Single-agent or Multi-agent?** - One context window is sufficient → **Single** - Tasks are genuinely independent, or require specialized context separation → **Multi** - When in doubt, start single. See [patterns.md](./references/patterns.md) **When to add orchestration?** - Only when simpler structures demonstrably fail. Never for architectural elegance alone. ## Red Flags If you see any of these, the design has likely drifted: - A tool that encodes "how to use it" in its interface → [Interface Wrapping](./references/tool-design.md) - An agent that reports its state more than it acts → [Meta-Reporting](./reference