design-an-interface

Overview of design-an-interface skill

The design-an-interface skill helps you design a module or API by forcing comparison instead of settling on the first reasonable shape. Its core method is simple: gather requirements, generate 3 or more radically different interface options in parallel, then compare them before choosing a direction.

What design-an-interface is for

Use design-an-interface when you need to answer questions like:

• “What should this module’s public API look like?”
• “Should this be one function, a class, or a builder?”
• “What should be exposed versus kept internal?”
• “Can we explore multiple API shapes before coding?”

This makes the skill especially useful for design-an-interface for API Development, library design, internal platform tooling, SDKs, and shared modules where interface mistakes are expensive to undo.

Best-fit users

The design-an-interface skill is a strong fit for:

• developers designing a new module from scratch
• teams refactoring a messy public API
• library authors comparing ergonomic tradeoffs
• AI users who want better-than-default interface proposals
• reviewers who need structured options, not one speculative answer

It is less useful if the interface is already fixed by an external standard or if you only need implementation help.

The real job-to-be-done

The real value is not “generate an API.” It is to de-risk interface decisions early by making multiple design directions visible at once. That matters because most bad APIs come from converging too fast on a familiar pattern.

What makes this skill different from a normal prompt

A generic prompt often produces one polished but arbitrary answer. design-an-interface instead pushes the model to:

1. gather requirements first
2. assign different design goals to parallel proposals
3. show usage examples, hidden internals, and tradeoffs
4. compare options before recommending one

That workflow creates better decision quality than “design an API for X.”

How to Use design-an-interface skill

design-an-interface install

Install the skill from the repository:

npx skills add mattpocock/skills --skill design-an-interface

If your AI coding environment supports Skills, install it there first, then invoke it when you are about to design or redesign a module interface.

Read this file first

Start with:

• SKILL.md

This repository entry is lightweight, so most of the useful guidance is in that one file. Read it before using the skill so you understand the required workflow: requirements first, then parallel designs, then comparison.

When to invoke design-an-interface in a workflow

Use design-an-interface usage before implementation, especially when:

• naming and shape are still undecided
• several API styles are plausible
• you expect future extension pressure
• you are designing for other developers, not just yourself
• the cost of public API churn is high

If you already know the exact surface area and only need code, this skill is probably overkill.

What input the skill needs

The skill works best when you provide:

• the module’s purpose
• who will call it
• the key operations
• constraints such as performance, compatibility, or existing conventions
• what should stay internal versus public

Minimal input can still work, but vague goals produce shallow designs. The skill is strongest when you give it enough context to generate meaningfully different options.

Turn a rough goal into a strong prompt

Weak input:

Design an interface for a cache module.

Stronger input:

Use design-an-interface for a TypeScript cache module used by backend services. Callers need get, set, and invalidation. Most traffic is read-heavy. We want a simple API for common usage, but we also need optional TTL support. Prefer hiding storage details. Must fit existing promise-based code and be easy to mock in tests.

Why this is better:

• it defines callers
• it names key operations
• it states common-case priorities
• it clarifies constraints
• it hints at what should remain internal

How the skill actually generates value

The central step is to create 3 or more radically different designs, not 3 small variations. Good differences include:

• minimal surface area vs flexible surface area
• function-first API vs class-based API
• optimize common path vs optimize extensibility
• familiar house style vs paradigm-inspired design

If the options look like cosmetic renames of the same idea, the run did not really use the skill well.

A practical design-an-interface prompt pattern

Use a prompt structure like this:

Use design-an-interface for a [language] module.

Problem:
[What the module must do]

Callers:
[Who uses it and how]

Key operations:
[List the important operations]

Constraints:
[Performance, compatibility, style, testing, migration, etc.]

Hide internally:
[What should not leak into the public API]

Please produce at least 3 radically different interface designs.
For each design include:
1. Interface signature
2. Example usage
3. What stays internal
4. Main tradeoffs

Then compare them and recommend one based on the stated constraints.

Good constraints to assign to different designs

The upstream skill suggests assigning different constraints to each sub-agent. In practice, these are useful design lenses:

• minimize method count
• maximize flexibility
• optimize the most common case
• mirror an existing ecosystem pattern
• prioritize testability
• minimize migration cost from a current API

This matters because “different designs” needs an explicit reason to diverge.

Suggested workflow for design-an-interface for API Development

A high-signal workflow looks like this:

1. define the module boundary
2. write down callers and operations
3. state non-negotiable constraints
4. ask for 3 to 4 radically different designs
5. review usage examples first, not signatures first
6. compare what each design hides internally
7. choose one direction
8. run a second pass to refine naming and edge cases

Reviewing usage examples first is important because interfaces often look fine in type form but feel awkward in actual call sites.

How to evaluate the outputs

Do not judge the designs only by elegance. Check:

• can callers do the common task simply?
• does the API leak internal mechanics?
• are edge cases forcing too many knobs into the main path?
• does the design match your codebase’s existing conventions?
• will future changes break callers?

The best proposal is usually the one with the clearest common-case path and the cleanest hiding of internal complexity.

Common adoption blocker

The biggest blocker is usually not installation. It is expecting the design-an-interface skill to choose the right API from underspecified requirements. If your requirements are fuzzy, the skill will still produce options, but the comparison will be weaker and more arbitrary.

design-an-interface skill FAQ

Is design-an-interface better than just asking for an API?

Usually yes, when the interface matters. A normal prompt often returns one plausible API. design-an-interface is better when you need structured exploration, explicit tradeoffs, and a recommendation grounded in constraints.

Is design-an-interface beginner-friendly?

Yes, if you already understand the problem domain. The skill gives a practical checklist: problem, callers, operations, constraints, and hidden internals. That structure helps beginners avoid skipping important design questions.

When should I not use design-an-interface?

Skip it when:

• an external spec already defines the interface
• you only need implementation details
• the module is tiny and private
• the API must mirror an existing framework exactly

In those cases, direct implementation prompts are usually faster.

Does it only work for public APIs?

No. design-an-interface usage also fits internal modules, service boundaries, adapters, and test-facing abstractions. It is useful anywhere interface shape affects maintainability or ease of use.

What languages and stacks fit this skill?

The method is language-agnostic. It works well for TypeScript, JavaScript, Python, backend services, libraries, and SDK-like modules. The main requirement is that interface design is a meaningful decision in your stack.

How many designs should I ask for?

At least 3. Fewer than that often collapses into a binary choice. More than 4 can be useful, but quality usually drops if the options are not truly distinct.

What does “radically different” actually mean?

It means differences in model, not just names. For example:

• function API vs object API
• minimal API vs configurable API
• stateful abstraction vs stateless helper
• explicit lifecycle vs implicit convenience path

If the usage examples feel interchangeable, the designs are not different enough.

How to Improve design-an-interface skill

Give better problem framing

The fastest way to improve design-an-interface results is to frame the module in terms of caller outcomes, not implementation pieces.

Less effective:

Build an interface around storage, retries, config, and parsing.

More effective:

Callers need to fetch remote data reliably with one simple default path, optional retry overrides, and no exposure to transport details.

This helps the model optimize for actual use instead of internal architecture.

Specify the primary user and common path

Many weak interface proposals try to satisfy everyone equally. Tell the skill:

• who the main caller is
• what they do most often
• what should feel easiest

That single detail often improves ergonomic quality more than adding extra technical constraints.

State what must stay hidden

A strong design-an-interface guide includes explicit encapsulation boundaries. Say what callers should not need to know, such as:

• storage backend details
• retry strategy internals
• network transport choices
• normalization steps
• cache invalidation mechanics

This pushes the skill toward cleaner module boundaries.

Force meaningful design divergence

If the first run gives similar answers, rerun with stronger per-design constraints such as:

• one design must be minimal and hard to misuse
• one must favor extension and composition
• one must optimize migration from the current API
• one must imitate a known paradigm in your ecosystem

Better constraints produce better comparisons.

Ask for usage examples that feel real

The quality of interface design is easiest to judge in call sites. Ask for:

• the most common usage
• one advanced usage
• one testing or mocking example

This exposes awkwardness early and makes the design-an-interface skill more practical than a pure signature exercise.

Watch for common failure modes

Typical weak outputs include:

• too many methods for a small module
• “flexibility” that leaks implementation details
• different designs that are only superficial variants
• APIs optimized for edge cases instead of the common path
• recommendations without clear tradeoff reasoning

Spotting these early makes iteration faster.

Improve the second pass, not just the first

After choosing a direction, run a refinement pass focused on:

• naming
• parameter ordering
• sensible defaults
• error handling shape
• test ergonomics
• migration concerns

The first pass should decide the model of the API. The second pass should polish usability.

Compare the chosen design against a rejection reason

A practical refinement trick: ask the model to explain why the chosen interface might fail in 6 months. This often reveals overexposed internals, missing extension seams, or convenience methods that should not be public.

Use design-an-interface with existing code carefully

If you are redesigning an existing module, provide:

• the current API
• pain points
• compatibility requirements
• what cannot break

Without that context, the skill may produce elegant but unrealistic proposals that are hard to adopt.

Keep the recommendation tied to your constraints

The best design-an-interface for API Development results happen when the final recommendation explicitly maps back to your priorities: simplicity, flexibility, performance, migration, or consistency. If the recommendation does not cite those constraints, ask for a revised comparison before you implement anything.