Design An Interface
Explore radically different API or module shapes in parallel before locking implementation.
Overview
Design an Interface is an agent skill most often used in Validate (also Build, Ship) that produces multiple radically different module or API designs in parallel for comparison before implementation.
Install
npx skills add https://github.com/vinvcn/mattpocock-skills-zh-cn --skill design-an-interfaceWhat is this skill?
- Runs 3+ parallel sub-agents, each forced into a distinct design constraint (minimal surface, flexibility, common-case, p
- Requirements pass covers problem, callers, key operations, constraints, and hidden vs exposed surface.
- Each option includes signature, usage example, internal hiding, and explicit trade-offs.
- Grounded in ‘Design It Twice’ from A Philosophy of Software Design.
- Hard comparison step before picking a single module shape to implement.
- Workflow targets 3+ parallel sub-agents with distinct design constraints.
- Four example constraint lenses: minimal methods, maximum flexibility, common-case optimization, and paradigm-inspired de
Adoption & trust: 1 installs on skills.sh; 499 GitHub stars.
What problem does it solve?
You are about to code an API or module from the first idea that came to mind, with no disciplined comparison of alternatives.
Who is it for?
Indie builders designing a new module, HTTP API, or agent tool surface when callers and constraints are known but the shape is not.
Skip if: Pure UI mockups, one-line wrappers with no design risk, or repos where the public API is frozen and only internal refactors are allowed.
When should I use this skill?
User wants to design an API, explore interface options, compare module shapes, or mentions ‘design it twice’.
What do I get? / Deliverables
You leave with three or more comparable interface proposals and trade-offs so you can pick one shape and hand off to implementation or planning skills.
- Three or more interface signatures with usage examples.
- Per-design encapsulation notes and trade-off summary.
- Comparison-ready presentation for picking a winning shape.
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Validate because the skill compares interface alternatives before you commit to code—classic ‘design it twice’ discovery. Prototype fits exploratory interface drafts and trade-off comparison, not production hardening or SEO work.
Where it fits
Spin three API sketches with different method counts before choosing a REST vs command-style surface.
Redesign a payment adapter interface without breaking existing callers.
Re-open interface debate when a PR exposes too many implementation types.
How it compares
Use instead of a single chat reply that lists one interface—this skill mandates parallel, constraint-driven alternatives.
Common Questions / FAQ
Who is design-an-interface for?
Solo developers and small teams using agentic IDEs who want API and module boundaries explored before writing production code.
When should I use design-an-interface?
In Validate when exploring module shapes, in Build when splitting a growing file into services, and in Ship review when reconsidering a leaky abstraction before merge.
Is design-an-interface safe to install?
It orchestrates design prompts and sub-agents; check the Security Audits panel on this Prism page and limit Task tooling if your environment restricts delegated runs.
SKILL.md
READMESKILL.md - Design An Interface
# Design an Interface 基于 “A Philosophy of Software Design” 中的 “Design It Twice”：你的第一个想法很可能不是最好的。生成多个根本不同的 designs，然后比较。 ## Workflow ### 1. Gather Requirements 设计前先理解： - [ ] 这个 module 解决什么问题？ - [ ] callers 是谁？（other modules、external users、tests） - [ ] key operations 是什么？ - [ ] 有哪些 constraints？（performance、compatibility、existing patterns） - [ ] 什么应该隐藏在内部，什么应该暴露？ 询问：“这个 module 需要做什么？谁会使用它？” ### 2. Generate Designs (Parallel Sub-Agents) 使用 Task tool 同时生成 3+ 个 sub-agents。每个都必须产出**根本不同**的 approach。 ``` Prompt template for each sub-agent: Design an interface for: [module description] Requirements: [gathered requirements] Constraints for this design: [assign a different constraint to each agent] - Agent 1: "Minimize method count - aim for 1-3 methods max" - Agent 2: "Maximize flexibility - support many use cases" - Agent 3: "Optimize for the most common case" - Agent 4: "Take inspiration from [specific paradigm/library]" Output format: 1. Interface signature (types/methods) 2. Usage example (how caller uses it) 3. What this design hides internally 4. Trade-offs of this approach ``` ### 3. Present Designs 每个 design 展示： 1. **Interface signature** — types、methods、params 2. **Usage examples** — callers 在实践中如何使用 3. **What it hides** — 保持在内部的 complexity 顺序展示 designs，让用户能在比较前吸收每个 approach。 ### 4. Compare Designs 展示所有 designs 后，按以下维度比较： - **Interface simplicity**：更少 methods、更简单 params - **General-purpose vs specialized**：flexibility vs focus - **Implementation efficiency**：shape 是否允许高效 internals？ - **Depth**：小 interface 隐藏大量 complexity（好）vs 大 interface 配薄 implementation（坏） - **Ease of correct use** vs **ease of misuse** 用 prose 讨论 trade-offs，不用 tables。突出 designs 分歧最大的地方。 ### 5. Synthesize 最好的 design 往往结合多个 options 的 insights。询问： - “哪个 design 最适合你的 primary use case？” - “其他 designs 中是否有值得合并的 elements？” ## Evaluation Criteria 来自 “A Philosophy of Software Design”： **Interface simplicity**：更少 methods、更简单 params = 更容易学习和正确使用。 **General-purpose**：能不改动就处理未来 use cases。但要警惕 over-generalization。 **Implementation efficiency**：interface shape 是否允许高效 implementation？还是迫使 internals 变别扭？ **Depth**：小 interface 隐藏大量 complexity = deep module（好）。大 interface 配薄 implementation = shallow module（避免）。 ## Anti-Patterns - 不要让 sub-agents 产出相似 designs；强制 radical difference - 不要跳过 comparison；价值在 contrast - 不要 implement；这里只讨论 interface shape - 不要基于 implementation effort 评价