From agent-artifex
Use when the user wants to design an MCP server, agent, chatbot, or tool-calling system for quality. This includes: designing tool descriptions, structuring parameters and schemas, writing error messages for LLM consumers, designing system prompts, planning multi-turn conversations, architecting tool sets, or designing response formats. Also use when someone says "how should I design", "what makes a good tool description", "how should I structure my errors", "design my MCP server", "how do I organize my tools", or any task where they want to follow evidence-based design principles before or while building.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-artifex:designThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Design principles for building quality AI services. For scaffolding new MCP servers, use `claude-api:mcp-builder`. For testing what you have built, use `agent-artifex:implement`. For diagnosing gaps, use `agent-artifex:assess`.
Design principles for building quality AI services. For scaffolding new MCP servers, use claude-api:mcp-builder. For testing what you have built, use agent-artifex:implement. For diagnosing gaps, use agent-artifex:assess.
| Reference | When to read |
|---|---|
agent-artifex/references/framework.md | Causal chain, testing pyramid, two-tier model |
agent-artifex/references/rubric.md | Six-component rubric for tool description scoring |
agent-artifex/references/evidence.md | Key empirical numbers and source citations |
Determine what the user is building and which design area applies:
Read the relevant file before designing.
| Design Area | Reference File | What it contains |
|---|---|---|
| Tool Description Design | references/tool-descriptions.md | 7 principles with evidence, rubric assessment criteria |
| Parameter & Schema Design | references/parameter-schema.md | 6 principles: type/meaning/effect, naming, enums, output schemas, arg counts, parallel calling |
| Error Message Design | references/error-messages.md | 5 principles: structured errors, four-part pattern, no internals, minimum density, protocol vs execution |
| System Prompt Design | references/system-prompts.md | 5 principles: capability overlap, conflict types, context budget, ordering, complementarity |
| Multi-Turn Conversation Design | references/multi-turn.md | 7 principles: context pressure, four factors, positioning, coreference, optimization, degradation, sequence preservation |
| Tool Set Architecture | references/tool-set-architecture.md | 7 principles: token budgeting, distribution limits, dynamic discovery, visibility limits, disambiguation, API coverage, one intent |
| Response Format Design | references/response-format.md | 6 principles: schema consistency, domain fidelity, dual parsing, verbosity control, two-phase quality, claim decomposition |
Design tool descriptions that maximize correct tool selection and invocation.
Before designing, read: references/tool-descriptions.md
Key principles:
Assessment checklist:
Design parameters and schemas that minimize invocation errors and ambiguity.
Before designing, read: references/parameter-schema.md
Key principles:
Assessment checklist:
Design error messages that help LLMs recover without human intervention.
Before designing, read: references/error-messages.md
Key principles:
Assessment checklist:
Design system prompts that complement tool descriptions without conflicting.
Before designing, read: references/system-prompts.md
Key principles:
Assessment checklist:
Design multi-turn interactions that maintain quality as conversations grow.
Before designing, read: references/multi-turn.md
Key principles:
Assessment checklist:
Design tool sets that scale without overwhelming the model's selection ability.
Before designing, read: references/tool-set-architecture.md
Key principles:
Assessment checklist:
Design tool result formats that maximize downstream usefulness.
Before designing, read: references/response-format.md
Key principles:
Assessment checklist:
Each design area maps to a specific link in the tool-use pipeline:
Tool Description Design ─────┐
Parameter & Schema Design ───┤→ Discovery → Tool Selection → Invocation → Response
Tool Set Architecture ───────┘ ↑ ↑ ↑
System Prompt Design ────────────────┘ │ │
Error Message Design ───────────────────────────────┘ │
Response Format Design ─────────────────────────────────────────┘
Multi-Turn Conversation Design → overlay across all links
agent-artifex:assess to check for gaps.agent-artifex:implement.npx claudepluginhub flexion/claude-domestique --plugin agent-artifexGuides designing AI agent tools with principles for workflows, context optimization, naming, input/output schemas, error handling, and evaluation.
Designs agent-facing tool interfaces: descriptions, schemas, response formats, naming conventions, actionable errors, MCP servers, and tool-set consolidation. Use when writing or debugging individual tools or a tool catalog.
Designs effective tools for AI agents, covering descriptions, namespacing, complexity reduction, and contracts. Use when creating, optimizing, debugging, or evaluating agent toolsets.