agent-design
Guidelines for designing tools and action spaces for AI agents. Use when building agent harnesses, designing tool interfaces, creating elicitation mechanisms, or optimizing agent-tool interactions. Covers progressive disclosure, tool design patterns, and lessons from Claude Code development.
npx skills add majiayu000/claude-skill-registry --skill agent-design-christophe1997-agent-extentions --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.
# Agent Design Guidelines ## Overview Designing tools for AI agents is as much art as science. The key principle: **give agents tools shaped to their own abilities** — which you discover by paying attention to their outputs. ### The Mental Model Imagine being given a difficult math problem. What tools would you want? | Tool | Limitation | |------|------------| | Paper only | Limited by manual calculations | | Calculator | Better, but requires knowledge to operate | | Computer | Most powerful, but requires coding skills | The right tool depends on **your own abilities**. Same for agents — design tools that match what the model can actually do well. ## Core Principles ### 1. Claude Must "Like" Calling the Tool Even the best designed tool doesn't work if Claude doesn't understand how to call it. - Test if the model naturally uses the tool - Read outputs to see if it's confused - Iterate on the interface until it "clicks" ### 2. Tools That Were Necessary Can Become Constraints As models improve: - Old workarounds become unnecessary - Previous "helps" become limitations - Constantly revisit assumptions **Example:** TodoWrite reminders helped older models but made newer ones think they c
- Overview
- The Mental Model
- Core Principles
- 1. Claude Must "Like" Calling the Tool
- 2. Tools That Were Necessary Can Become Constraints
- 3. Progressive Disclosure Over Context Bloat
- 4. High Bar for New Tools
- Design Patterns
- Pattern: Structured Elicitation (AskUserQuestion)
- Pattern: Task Coordination (Task Tool)
- Pattern: Context Building (Search Tools)
- Pattern: Capability Without Tools (Subagents)
- Tool Design Checklist
- Anti-Patterns
What does the agent-design skill do?
Guidelines for designing tools and action spaces for AI agents. Use when building agent harnesses, designing tool interfaces, creating elicitation mechanisms, or optimizing agent-tool interactions. Covers progressive disclosure, tool design patterns, and lessons from Claude Code development.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill agent-design-christophe1997-agent-extentions --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 majiayu000/claude-skill-registry, a repository with 534 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.