ai-agent-design
Comprehensive guide to designing, building, and operating AI agents. Covers agent architecture, tool use patterns, memory systems, orchestration strategies, planning approaches, error recovery, and safety guardrails for production-grade agent systems.
Profile →npx skills add cosmicstack-labs/mercury-agent-skills --skill ai-agent-design --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Describes a framework for designing, building, and operating AI agents. It instructs on establishing agent tools and memory systems, orchestration patterns, planning approaches, error handling, and safety guardrails for production-grade agent systems.
How it works
The skill lays out core principles (agents are tools, autonomy on a spectrum, cache everything, fail predictably, safety first). It defines an agent maturity model (L1 to L5) with characteristics across tool use, memory, and autonomy. It provides patterns for tool use via function calling and JSON-like schemas, and demonstrates tool definitions in Python with execute methods and schemas. It describes memory systems (short-term, long-term, episodic, semantic) and how to store and recall data, including example Python classes for memory components and strategies (Last-N, Sliding Window, Summarization, RAG). It covers single-agent and multi-agent orchestration (Supervisor, Routing patterns) with code sketches for coordinating or routing tasks among specialized agents. Planning strategies are outlined with ReAct (reasoning + acting) and Plan-and-Execute patterns, including example code flow for iterative tool calls and plan execution. It addresses error recovery concepts (Fail Predictably) and highlights guardrails and safety considerations before feature development.
When to use it
Use when designing or evaluating an AI agent system architecture, especially for production-grade implementations that require memory, orchestration, planning, and safety controls. Applicable to teams building tool-use patterns, memory strategies, and multi-agent coordination frameworks.
What it can touch
Tool use concepts are described, including function calling and tool schemas. It references tools like function calls and multiple tool interactions, with Python code patterns for implementing tools and memory modules. Specific tool names or external APIs are shown as examples (e.g., search tools, vector stores, databases) within code blocks to illustrate integration patterns.
Caveats
The material presents architectural patterns and design principles but does not guarantee specific outcomes or performance metrics. It emphasizes guardrails and safe design, stating that agents should fail gracefully and require appropriate safety checks; no guarantees of success are provided.
# AI Agent Design ## Core Principles ### 1. Agents Are Tools, Not Teammates An AI agent is a system that uses an LLM to reason and take actions. It is not a person — it has no goals, desires, or understanding. Design agents as tools with clear boundaries, not as autonomous collaborators. ### 2. Autonomy is a Spectrum Full autonomy is rarely the goal. The best agents operate on a spectrum: more human oversight for critical actions, more autonomy for routine tasks. Design for the level of autonomy that matches the risk. ### 3. Cache Everything, Guess Nothing Agents have no memory between calls unless you design it. Every interaction, tool result, and decision must be explicitly stored and retrieved. Assume the agent remembers nothing unless you program it to. ### 4. Fail Predictably Every agent will fail. The question is how it fails. Design for graceful degradation: when uncertain, ask for help. When stuck, escalate. When broken, stop safely. ### 5. Safety First, Speed Second A fast agent that takes unauthorized actions is worse than a slow agent that double-checks. Build guardrails before building features. --- ## Agent Maturity Model | Level | Name | Characteristics | Tool Use | M
- Core Principles
- 1. Agents Are Tools, Not Teammates
- 2. Autonomy is a Spectrum
- 3. Cache Everything, Guess Nothing
- 4. Fail Predictably
- 5. Safety First, Speed Second
- Agent Maturity Model
- Progression Path
- Tool Definition Patterns
- Function Calling / Tool Use
- Tool Schema Pattern (OpenAI-style)
- Tool Definition Best Practices
- Tool Implementation Pattern (Python)
- Tool Categories
What does the ai-agent-design skill do?
Comprehensive guide to designing, building, and operating AI agents. Covers agent architecture, tool use patterns, memory systems, orchestration strategies, planning approaches, error recovery, and safety guardrails for production-grade agent systems.
How do I install it?
Run `npx skills add cosmicstack-labs/mercury-agent-skills --skill ai-agent-design --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From cosmicstack-labs/mercury-agent-skills, a repository with 364 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.