How the design-an-interface Skill Generates Multiple Interface Options

The design-an-interface skill generates multiple interface options by spawning three or more parallel sub-agents with deliberately conflicting design constraints, then comparing their outputs across five evaluation criteria to identify the optimal architectural approach.

The design-an-interface skill in the mattpocock/skills repository implements a structured workflow for API design that avoids premature convergence on a single solution. Instead of producing one interface proposal, the skill orchestrates a divergent exploration process defined in design-an-interface/SKILL.md that forces competing designs to surface their inherent trade-offs.

The Six-Step Divergent Workflow

The skill executes a multi-step pipeline that transforms vague module descriptions into radically different interface proposals. Each step is explicitly defined in the skill's source configuration.

Step 1: Requirement Gathering

Before generating any code, the skill interrogates the user to clarify the module's purpose. According to the source in design-an-interface/SKILL.md lines 12-20, it captures:

• The specific problem the module solves
• Its intended callers and usage contexts
• Key operations required
• Any architectural constraints or environmental limitations

This requirements gathering ensures subsequent designs address real-world needs rather than hypothetical scenarios.

Step 2: Parallel Agent Orchestration with the Task Tool

The core divergence mechanism begins with the Task tool. As implemented in lines 24-40 of SKILL.md, the skill launches three or more sub-agents simultaneously. Each agent receives identical requirements but a different design constraint, such as:

• "Minimize method count" (e.g., ≤ 2 methods)
• "Maximize flexibility" (support streams, buffers, and URLs)
• "Optimize for the most common case" (fast-path single operations)

This parallel execution ensures the generated interfaces explore distinct architectural shapes rather than minor variations of the same theme.

Step 3: Constraint-Driven Prompting

Each sub-agent operates from a standardized prompt template defined in lines 41-46 of the skill definition:

Design an interface for: [module description]
Requirements: [gathered requirements]
Constraints for this design: [specific constraint]

The prompt forces every agent to produce four mandatory sections:

1. Interface signature – TypeScript types and method definitions
2. Usage example – Concrete code demonstrating caller interaction
3. Hidden internals – What implementation details the interface conceals
4. Trade-offs – Explicit acknowledgment of what the design sacrifices

Step 4: Structured Output Collection

After the parallel agents complete execution, the skill aggregates their responses. Per lines 48-55 of SKILL.md, it presents each design sequentially while preserving the four-section structure (signature, usage, hidden internals, trade-offs). This standardized formatting enables direct comparison between proposals that may differ radically in scope and philosophy.

Step 5: Comparative Analysis Across Evaluation Criteria

The skill then contrasts the proposals using five specific evaluation criteria defined in lines 58-66:

• Interface simplicity – Number of methods and cognitive load
• General-purpose vs. specialized flexibility – Breadth of supported use cases
• Implementation efficiency – Performance characteristics and resource usage
• Depth – Degree of implementation hidden behind a small interface versus shallow exposure
• Ease of correct use vs. ease of misuse – API ergonomics and error prevention

This structured comparison prevents subjective preference from dominating the selection process.

Step 6: Synthesis and Selection

Finally, the skill prompts the user to select the preferred approach and identify elements from discarded designs worth incorporating. According to lines 70-76 of the source, this synthesis step allows for hybrid interfaces that combine the error handling of one design with the flexibility of another, producing an optimized final specification.

Installing and Using the Skill

Add the skill to your project using the Skills CLI:

npx skills@latest add mattpocock/skills/design-an-interface

Once installed, invoke the skill by describing your module. For example, requesting an interface for a file storage service triggers the parallel generation workflow:

**User:**  
Design an interface for a file-storage service that handles uploads, downloads, and deletions.

**Skill (after requirements gathering):**  
Requirements: Store binary blobs, retrieve by ID, delete old blobs, work in browser and Node.js.

**Agent Outputs:**

**Agent 1** (Minimize method count):

```typescript
interface SimpleStorage {
  put(data: Uint8Array): Promise<string>;
  get(id: string): Promise<Uint8Array>;
}
// Hides: deletion logic, chunking, metadata
// Trade-off: No explicit delete, limited to whole files

Agent 2 (Maximize flexibility):

interface FlexibleStorage {
  upload(source: Buffer | ReadableStream | URL): Promise<FileRef>;
  download(ref: FileRef, format?: 'buffer' | 'stream'): Promise<unknown>;
  delete(ref: FileRef): Promise<void>;
  list(prefix?: string): AsyncIterable<FileRef>;
}
// Hides: transport layer, backpressure handling
// Trade-off: Larger API surface, requires more caller knowledge

Agent 3 (Optimize for common case):

interface FastStorage {
  upload(file: File): Promise<string>;
  download(id: string): Promise<Blob>;
  bulkDelete(ids: string[]): Promise<number>;
}
// Hides: streaming internals, error retry logic
// Trade-off: Assumes browser File objects, less suitable for Node streams

Comparison:
Agent 1 offers minimalism but sacrifices deletion; Agent 2 supports streaming but adds complexity; Agent 3 optimizes for browser uploads but limits server flexibility.

User:
Prefer Agent 2's flexibility but want Agent 1's minimal error surface.

Skill:
Proposes hybrid: streaming support with simplified error types.

## Why Parallel Constraints Produce Better Interfaces

The **radical divergence** enforced by conflicting constraints prevents the "local maximum" problem common in single-design approaches. By forcing one agent to minimize method count while another maximizes flexibility, the skill ensures that fundamental architectural tensions—such as simplicity versus power—are surfaced explicitly rather than buried in implicit assumptions.

This methodology aligns with the architectural principles described in related skills like [`improve-codebase-architecture/SKILL.md`](https://github.com/mattpocock/skills/blob/main/improve-codebase-architecture/SKILL.md), which emphasizes that deep modules (small interfaces hiding complex implementations) require conscious exploration of the simplicity/flexibility spectrum. The parallel generation process makes this exploration concrete and selectable.

## Summary

- The **design-an-interface** skill uses the **Task** tool to spawn three or more sub-agents simultaneously with conflicting constraints.
- Each agent outputs a standardized four-part design: **interface signature**, **usage example**, **hidden internals**, and **trade-offs**.
- Designs are evaluated against five criteria: **simplicity**, **flexibility**, **efficiency**, **depth**, and **usability**.
- The workflow is defined in [`design-an-interface/SKILL.md`](https://github.com/mattpocock/skills/blob/main/design-an-interface/SKILL.md) and installable via `npx skills@latest add mattpocock/skills/design-an-interface`.
- This **divergent design process** prevents premature convergence and surfaces architectural trade-offs that single-design approaches often obscure.

## Frequently Asked Questions

### How many interface options does the skill generate by default?

The skill generates **at least three** parallel interface proposals by default, though this can be configured by modifying the number of sub-agents spawned via the Task tool. Each agent receives a distinct constraint—such as minimizing method count or maximizing flexibility—to ensure the designs explore genuinely different architectural approaches rather than minor variations.

### What evaluation criteria does the skill use to compare interfaces?

According to [`design-an-interface/SKILL.md`](https://github.com/mattpocock/skills/blob/main/design-an-interface/SKILL.md) lines 58-66, the skill evaluates proposals on five specific criteria: **interface simplicity** (cognitive load), **general-purpose vs. specialized flexibility**, **implementation efficiency**, **depth** (amount of functionality hidden behind the interface), and **ease of correct use versus ease of misuse** (API safety).

### Can I combine elements from different generated interfaces?

Yes. The final step of the workflow explicitly asks users to identify which design best fits the primary use case and whether elements from other designs should be incorporated. This synthesis step supports creating hybrid interfaces that combine, for example, the flexibility of one design with the error handling simplicity of another.

### Where is the skill's workflow logic defined?

The complete generation logic, prompt templates, and evaluation criteria are defined in **[`design-an-interface/SKILL.md`](https://github.com/mattpocock/skills/blob/main/design-an-interface/SKILL.md)** within the `mattpocock/skills` repository. This file contains the Task tool configurations and constraint definitions that orchestrate the parallel sub-agent execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}