agent-product-design — Claude Code skill for agent product design
This Claude Code skill turns requirements into agent product designs and clickable prototypes. It maps the task flow, permissions, evidence, and human review points.
MIT ★ 6,467 updated 2026-11-16
npx skills add mdiri-ai/SoduWork --skill agent-product-design -a claude-codeWhat agent-product-design does
The skill turns a brief for an AI assistant or agent into product requirements and a clickable prototype. It produces requirements.md with users, scenarios, and acceptance criteria, agent-design.md covering the agent’s boundaries and tools, plus prototype.html and a review that connects each criterion to visible evidence.
The design traces a task from planning through execution and verification to delivery. The prototype must show a normal completion, missing information or a permission gate, and a failure followed by retry or human takeover. A self-contained HTML prototype simulates interactions locally; it does not call remote models, CDNs, or live enterprise systems.
What it helps with
- define acceptance criteria for an AI agent
- show the agent’s active plan and progress
- design a permission gate for consequential actions
- represent failure, retry, and human handoff
- connect acceptance criteria to visible prototype states
Example prompts for the agent
- Design an AI assistant for processing requests and define its boundaries, tools, and human approval points.
- Build a clickable HTML prototype with a normal task flow, a permission gate, and a failure path.
- Write acceptance criteria and map each one to an observable part of the prototype.
How to install agent-product-design
1Skills CLI (Vercel)
npx skills add mdiri-ai/SoduWork --skill agent-product-design -a claude-code2Manually: put the files in place
~/.claude/skills/agent-product-design/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/agent-product-design/
1Skills CLI (Vercel)
npx skills add mdiri-ai/SoduWork --skill agent-product-design -a codex2Manually: put the files in place
.agents/skills/agent-product-design/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add mdiri-ai/SoduWork --skill agent-product-design -a cursor2Manually: put the files in place
.cursor/skills/agent-product-design/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install mdiri-ai/SoduWork skills/agent-product-design2Manually: put the files in place
.github/skills/agent-product-design/SKILL.md1Skills CLI (Vercel)
npx skills add mdiri-ai/SoduWork --skill agent-product-design -a gemini-cli2Platform CLI
gemini skills install https://github.com/mdiri-ai/SoduWork --path skills/agent-product-designManually: put the files in place
.devin/skills/agent-product-design/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about agent-product-design
How do I install agent-product-design in Claude Code?
Run npx skills add mdiri-ai/SoduWork --skill agent-product-design -a claude-code. The skill file is at ~/.claude/skills/agent-product-design/SKILL.md.
What does agent-product-design do?
It helps shape an AI agent or human-AI workflow by defining requirements, agent behavior, and acceptance checks, then outlining a clickable prototype.
Which states should an agent-product-design prototype cover?
It should show a normal completion, missing information or a permission gate, and a failure followed by retry or human takeover. A self-contained HTML prototype simulates these interactions locally.
Source text
SKILL.md · MIT
--- name: agent-product-design description: Design enterprise agent products and interactive prototypes that make goals, plans, tool use, evidence, permissions, human gates, recovery, and final delivery understandable and controllable. Use when turning a requirement into an AI assistant, autonomous agent, human-AI workflow, agent workspace, or clickable agent-product prototype. --- # Agent Product Design Design the work system, not a chatbot shell. Make the user understand what the agent is doing, why it is allowed to do it, what evidence proves completion, and where a human remains in control. ## Deliverables Produce these artifacts: 1. requirements.md — users, jobs, scope, scenarios, information architecture, exceptional states, and testable acceptance criteria. 2. agent-design.md — the agent contract, autonomy, tools, memory, gates, evidence, recovery, and evaluation. 3. prototype.html — a self-contained clickable prototype that demonstrates the core work loop. 4. A review conclusion that maps every acceptance criterion to visible evidence. Do not substitute a feature list, dashboard, static landing page, or chat mockup for an agent product. ## Work from outcome to interaction ### 1. Define the work State: - Who requests the work and who receives the result. - The business outcome, not merely the requested screen. - Inputs, attachments, systems, constraints, and sensitive data. - The completion standard and evidence a reviewer can inspect. - What remains outside the first deliverable. If the input is incomplete, choose the smallest reversible assumption and record it. Do not invent integrations, credentials, data, or production capability. ### 2. Define the agent contract For each agent role, specify: - Mission and boundaries. - Inputs and normalized working context. - Plan and progress representation. - Allowed tools, data sources, Skills, and MCP connections. - Permission mode: read-only, confirm before change, or pre-authorized action. - Memory scope and retention. - Human gates and escalation conditions. - Evidence captured for each consequential action. - Retry, resume, cancellation, and rollback behavior. - Final deliverable and quality evaluation. Prefer MCP or APIs, then browser automation, then computer control. Never imply a tool exists when it is not configured. ### 3. Design the visible work loop Use one coherent lifecycle: 1. Understand the request. 2. Form or update a plan. 3. Execute visible steps. 4. Ask for permission only at real gates. 5. Verify against completion criteria. 6. Deliver results and evidence. 7. Capture feedback for future improvement. The primary surface is the current task or conversation. Keep secondary details progressive: - Show short narrative updates at meaningful stage changes. - Collapse commands, reads, writes, and browser actions into compact activity rows. - Let users inspect details without flooding the main conversation. - Keep the active plan and current step visible. - Present files as direct links and runnable web results in a preview surface. - Separate evidence from marketing claims. ### 4. Prototype real states The prototype must include deterministic local interactions for at least: - A normal end-to-end completion. - Missing information or a permission gate. - Tool or validation failure followed by retry or human takeover. Also cover loading, empty, paused, cancelled, and completed states where relevant. A button must change meaningful state; decorative controls do not count as interaction. For a self-contained HTML prototype, simulate the agent locally with an explicit state machine. Label external integrations as prototype simulations. Do not call remote models, CDNs, or live enterprise systems. ### 5. Establish a product-specific visual system Use the actual domain, users, artifacts, vocabulary, and risk level to choose layout, type, color, density, and motion. Avoid generic AI gradients, oversized empty cards, decorative robot imagery, and a dashboard made from interchangeable tiles. Give the product one clear visual signature. Keep body text readable, controls consistent, keyboard focus visible, contrast sufficient, and motion respectful of reduced-motion preferences. Check desktop and narrow layouts. ## Quality gate Reject the result if any statement is true: - The product is only a chat box with canned replies. - Users cannot see the active goal, plan, progress, or completion standard. - Tool use is hidden or dumped as unstructured logs. - Permissions and human gates are absent or decorative. - Results lack inspectable files, evidence, or validation. - Failure, retry, resume, and handoff are not represented. - The prototype claims real integrations it does not have. - The main scenario cannot be completed by clicking through the prototype. - The visual design could be reused unchanged for an unrelated product. Before delivery, run the main, gate, and failure paths; inspect the rendered page; and map every acceptance criterion to an observable state or artifact.
© mdiri-ai · MIT · mdiri-ai/SoduWork