# Design

> Design stable interfaces that are hard to misuse. Use when defining contracts, module boundaries, or public APIs.

- **Type:** Skill
- **Install:** `agentstack add skill-cniska-skills-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cniska](https://agentstack.voostack.com/s/cniska)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cniska](https://github.com/cniska)
- **Source:** https://github.com/cniska/skills/tree/main/skills/design

## Install

```sh
agentstack add skill-cniska-skills-design
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Design

Design interfaces that are hard to misuse, easy to extend, and stable under change. Applies to API contracts, module boundaries, config schemas, and any surface where components interact.

## Principles

### Contract first

Define the interface before implementing it. The schema is the contract — implementation follows.

### Hyrum's Law

All observable behaviors of your system will be depended on by somebody, regardless of what you promise in the contract. Every public behavior becomes a de facto commitment. Be deliberate about what you expose.

### Prefer addition over modification

Extend interfaces by adding optional fields rather than changing existing ones. Changing a field's type or removing it breaks consumers silently. Adding is safe; modifying is not.

When different behaviors carry different intent, prefer separate variants or schemas over a single shared shape with conditionally meaningful fields.

### Validate at boundaries

Trust internal code. Validate at system boundaries — API payloads, config files, external inputs. Don't scatter validation deep inside the call stack.

### Predictable naming

Follow established project conventions consistently. When no convention exists, prefer explicit and descriptive over terse and clever.

## Workflow

1. **Identify the boundary.** What calls this? What does it return? Who else might consume it? Spawn **fast-tier** readers for existing analogous interfaces in the codebase — gather patterns before proposing new ones.
2. **Define the schema.** Schema first, types inferred. Include descriptions for non-obvious fields.
3. **Design for the common case.** Make the default behavior correct. Require explicit opt-in for unusual behavior. The synthesis pass — weighing tradeoffs, choosing the contract shape — benefits from a **powerful-tier** model with high reasoning effort.
4. **Review for misuse.** Can a caller get into a bad state by passing valid-looking but wrong data? Add discriminants or branded types where confusion is likely.
5. **Check extensibility.** Can this be extended without modifying existing consumers?

## See also

- `architecture-review` for boundary and dependency integrity
- `security-review` for trust-boundary risk review

## Red flags

- Interfaces that require callers to know implementation details
- Fields that mean different things depending on context
- Breaking changes disguised as bug fixes
- Validation scattered through the call stack instead of at the boundary

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cniska](https://github.com/cniska)
- **Source:** [cniska/skills](https://github.com/cniska/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cniska-skills-design
- Seller: https://agentstack.voostack.com/s/cniska
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.