design-an-api

Featured

Designs the contract for an API change inside one codebase — a component's props, a function surface, URL or query parameters, an event payload, or a module boundary — through a discovery pass, an options document with one recommendation, a question round, and an adversarial validation round, with every element of the contract justified from one stated goal. Use when you want to design, shape, decide, or nail down an interface, contract, signature, or API change for a capability you can already describe, sized for roughly one pull request. Produces a design document and changes no code. Does not specify what a feature should do — use plan-a-feature. Does not plan delivery or sequencing — use plan-implementation. Does not assess the architecture of existing code — use architectural-analysis. Does not write the code — use tdd. Does not restructure existing code — use refactor. Runs its rounds without pausing for review; to review each round as it lands, use pairing.

Code & Development 273 stars 23 forks Updated 2 days ago MIT

Install

View on GitHub

Quality Score: 94/100

Stars 20%
81
Recency 20%
100
Frontmatter 20%
70
Documentation 15%
100
Issue Health 10%
50
License 10%
100
Description 5%
100

Skill Content

## Project Context - git installed: !`which git 2>/dev/null || echo "not installed"` - current branch: !`git branch --show-current 2>/dev/null || echo "no git branch"` - default branch: !`git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown` - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` - personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md` probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used. ## Operating Principles Read these before dispatching anything. They constrain every step below. - **A stated goal is required, and it is the scope governor.** This skill designs a contract in service of one named goal: a ticket, an issue, a written requirement, or a described capability. If no goal resolves, stop and ask for one BECAUSE without a goal there is nothing to justify the design against, and the run degrades into de...

Details

Author
testdouble
Repository
testdouble/han
Created
4 months ago
Last Updated
2 days ago
Language
Shell
License
MIT

Integrates with

Bundled in these plugins

Similar Skills

Semantically similar based on skill content — not just same category

AI & Automation Listed

api-design

Design a public contract (HTTP/REST, RPC, webhook, CLI, or library API) before building it — consumers & compatibility promise first, resource model in the domain language, the contract checklist (error model, pagination, idempotency, partial updates, versioning), worked request/response examples including errors, and a consumer's-eyes review pass. TRIGGER when: designing or extending an API/endpoint/webhook/CLI surface or a library's public interface — "design the API", "какой сделать контракт/эндпоинт", adding endpoints consumers outside this repo will call. DO NOT TRIGGER when: designing an internal module seam (use /codebase-design), or the contract exists and the question is shipping a change to it safely (use /rollout).

2 Updated 2 days ago
mik2win
Code & Development Featured

plan-a-feature

Builds a feature specification from scratch through a relentless, evidence-based interview that walks the design tree decision-by-decision, resolving dependencies as it goes. Use when the user wants to plan, design, scope, specify, or flesh out a new feature, capability, or system behavior before implementation. Produces a feature specification focused on system behaviors, not implementation detail. Does not plan a restructure of code that already exists — use plan-a-change. Does not refine or stress-test an existing plan — use iterative-plan-review. Does not document already-built features — use project-documentation. Does not design the contract for an interface — use design-an-api. Does not research open-ended options before there is a feature to specify — use research. Does not map the bounded contexts of existing code — use ddd-analysis.

273 Updated 2 days ago
testdouble
Code & Development Featured

plan-a-change

Plans an architecture-driven change to code that already exists: module boundaries, type responsibilities, layering, coupling, and the public surface a revision moves. Produces a buildable change plan that names the types, modules, and methods involved and records the surface delta each change makes. Use when the user wants to plan, scope, or sequence a restructure, extraction, split, consolidation, responsibility shift, or API revision of existing code, including "these responsibilities are wrong, plan the fix". Does not assess an area and stop at findings — use architectural-analysis. Does not specify new behavior — use plan-a-feature. Does not diagnose a bug — use investigate. Does not write the code — use refactor to restructure it or tdd to build it.

273 Updated 2 days ago
testdouble