Skip to content
Skills Library
Programming · Planning

api-and-interface-design

/api-and-interface-design

Use when defining a public API, CLI, webhook, or SDK surface — lock the contract first so compatibility, validation, and versioning stay intentional instead of accidental

Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when defining a public API, CLI, webhook, or SDK surface — lock the contract first so compatibility, validation, and versioning stay intentional instead of accidental

Original author description

Use when defining a public API, CLI, webhook, or SDK surface — lock the contract first so compatibility, validation, and versioning stay intentional instead of accidental

How it works

  1. When to Use
  2. When NOT to Use
  3. Workflow
  4. Example
  5. Common Mistakes
  6. Verification
  7. See Also
Original SKILL.md headings · 190 lines, 1,058 words
SKILL.md preview
---
name: api-and-interface-design
description: Use when defining a public API, CLI, webhook, or SDK surface — lock the contract first so compatibility, validation, and versioning stay intentional instead of accidental
metadata:
  category: development
  agent_type: general-purpose
  origin: ported and adapted from addyosmani/agent-skills
---

# API and Interface Design

Define the contract before the implementation. This skill is for **public or cross-team interfaces**
where downstream consumers can depend on every observable behavior, including the ones you did not
mean to promise.

## When to Use

- Designing a new public HTTP API, CLI command, webhook, SDK surface, or plugin contract
- Changing an existing interface that other teams, tools, or customers already consume
- Clarifying breaking-change policy before implementation starts
- Auditing a CLI or SDK that already shipped — see "Audit mode" below
- Tightening the interface section of `spec-driven-development` for a compatibility-sensitive feature

## When NOT to Use

| Instead of api-and-interface-design | Use |
|-------------------------------------|-----|
| Internal implementation design inside one module | `spec-driven-development` |
| Writing user-facing docs for a finished API | `api-documentation` |
| Retiring or replacing an old interface | `deprecation-and-migration` |
| Narrow bug fixes with no contract change | do the fix directly |

## Workflow

### 1. Identify the real contract boundary

Write down:

- **Who consumes this interface?** Humans, services, CLI users, integrations, third-party developers
- **What is observable?** Inputs, outputs, error codes, ordering, timing, idempotency, pagination, retries
- **What must stay stable?** Field names, response structure, exit codes, callback payloads, invariants

If the consumer or stability target is unclear, you are not ready to implement.

### 2. Draft the contract before code

Create a contract document or spec section before touching implementation:

```markdown
## Interface Contract: createWidget

**Interface type**: REST API / CLI / SDK / webhook
**Consumers**: Internal services + external customers
**Stability**: stable / beta / experimental

### Inputs
- Method / command / function name:
- Required parameters:
- Optional parameters:
- Validation rules:

### Outputs
- Success shape:
- Error shape:
- Ordering / pagination guarantees:

### Invariants
- [Behavior that must remain true]

### Non-Goals
- [What this interface deliberately does not promise]
```

### 3. Run a Hyrum's Law review

For every observable behavior, ask:

- Is this behavior intentionally part of the contract?
- If consumers start depending on it, can we support it long-term?
- If not, should we remove it, hide it, or document that it is non-contractual?

Common accidental contracts:

- Stable ordering without documenting it
- Error message wording used by scripts
- Undocumented default values
- Side effects triggered by read operations
- Field presence that is only an implementation artifact

### 4. Design validation at the trust boundary

Validation should happen where untrusted input enters the system:

- HTTP body, query params, headers
- CLI args and environment variables
- Webhook payloads
- Files or user-supplied configuration

Do not scatter the same runtime validation through every internal layer. Define:

- Accepted input shape
- Rejection rules
- Standard error envelope or exit code mapping
- Which invariants are guaranteed after boundary validation succeeds

### 5. Choose the compatibility strategy

| Change type | Default strategy |
|-------------|------------------|
| Additive field | Make optional first; define default behavior |
| Renamed field | Add new field, deprecate old one, keep overlap window |
| Semantic change | Version the interface or add a new endpoint/flag |
| Removed capability | Publish a migration path before removal |

If you cannot explain the migration path in two or three sentences, the change is not ready.

### 6. Hand off to implementation planning

Once the contract is stable:

1. Feed it into `spec-driven-development`
2. Identify tests that prove the contract
3. Implement the smallest slice that honors the contract exactly

### Audit mode — checking a surface that already shipped

When the interface exists and the question is "is this contract actually good?", audit it from evidence
instead of redesigning it. Stay read-only unless asked to fix.

1. Write a one-line scope receipt before reading code, so the audit cannot quietly widen:
   `Scope: audit; surfaces: <commands/exports/config>; excludes: <UI, docs prose, private internals>`
2. Run safe probes against a local build:
   - **CLI**: `--help`, `--version`, one success path, one invalid-input path, and the same command
     with stdout redirected to a new temporary file outside the worktree to see non-TTY output;
     read it, then delete it. Use `--dry-run` where it exists; never trigger a real mutation to test
     the experience.
   - **Package**: check what `exports`/`bin` actually resolve to after a build. Packing can run
     lifecycle scripts — read them first, or probe a disposable checkout.
3. Check the developer-facing contract: consistent naming and argument order, one predictable return
   shape, errors that say what failed and how to fix it, and exit codes a script or agent can branch on.
4. Stop when each behavior is proven, disproven, private, or out of scope. Report findings tied to the
   probe that showed them.

Adapted from the `dx-audit` skill in `mblode/agent-skills` (MIT).

## Example

```markdown
## Interface Contract: `copilot skill install`

**Interface type**: CLI
**Consumers**: Developers using Copilot CLI
**Stability**: beta

### Inputs
- Command: `copilot skill install <url-or-path>`
- Optional flags: `--dry-run`, `--force`
- Validation rules:
  - URL must be HTTPS or GitHub shorthand
  - Local path must contain a valid skill directory

### Outputs
- Exit code `0`: install succeeded
- Exit code `1`: validation failure
- Exit code `2`: network or fetch failure

### Invariants
- Installed skill is validated before being written
- `--dry-run` never mutates the filesystem

### Non-Goals
- Private repository authentication
- Version pinning
```

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Letting implementation details leak into the contract | Document only consumer-visible behavior |
| Treating every internal helper as a public interface | Limit this skill to external or cross-team boundaries |
| Adding validation everywhere "just in case" | Validate once at the boundary, then trust the normalized input |
| Delaying breaking-change planning until after coding | Choose the migration strategy before implementation |

## Verification

- [ ] Consumers and stability target are explicitly named
- [ ] Inputs, outputs, invariants, and non-goals are written before coding
- [ ] Observable but accidental behaviors were reviewed for Hyrum's Law risk
- [ ] Boundary validation and error semantics are defined
- [ ] Breaking changes have a migration or versioning strategy

## See Also

- [`spec-driven-development`](../spec-driven-development/SKILL.md) — turn the contract into an implementation plan
- [`api-documentation`](../../documentation/api-documentation/SKILL.md) — publish user-facing API docs
- [`deprecation-and-migration`](../deprecation-and-migration/SKILL.md) — retire or replace old interfaces safely

Versions

RepositoryScoreLicence
This page · drvoss/everything-copilot-cli100MIT
lucasouzadev/agent-kit-skill100MIT
TheAstroByte/astrobyte-agent-skills100MIT
FrancoStino/opencode-skills-collection100MIT
sickn33/agentic-awesome-skills100MIT
Alter-ai/skill-lab100MIT
georgewangyu/GeorgeCodingAgent100MIT
vinvcn/addyosmani-agent-skills-zh100MIT
addyosmani/agent-skills100MIT

Database snapshot: 13.11.2026 · package version f884319b6545 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 4 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90design
    Design or review an API contract: resources, error conventions, pagination, versioning, and security, then validate the OpenAPI file. Use when defining an API.
  • 95api-design
    Use when designing new REST endpoints, reviewing an existing API contract, adding pagination or filtering, planning a versioning strategy, or building a public or partner-facing API.
  • 90api-contracts
    Design or change an HTTP API contract for new or existing consumers. Use when endpoints, schemas, errors, authentication, versioning, or compatibility are changing.
  • 100rest-api-design
    Use when defining or reviewing HTTP API contracts, resource operations, representations, status and error semantics, pagination, compatibility, or versioning.
  • 90dev-api-contract-review
    Use to design or review API contracts, auth, pagination, versioning, errors, compatibility, and OpenAPI/GraphQL shape.
  • 90api-design
    Contract-first API design for stable, evolvable interfaces. Use whenever defining a new API endpoint, inter-service boundary, or modifying an existing contract. Includes backward compatibility checklist and error contract specification.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.