api
Use to derive the API contract for a feature — an OpenAPI 3.1 document at docs/features/{slug}/contracts/openapi.yaml plus a drift/sync report (and an events doc when the feature has async flows). Triggers on "api for {slug}", "openapi for {slug}", "API contract for {slug}", "lock the interface for {slug}", "events for {slug}", "/sdd:api {slug}", "контракт API для {slug}", "OpenAPI для {slug}", "опиши ендпоінти". The contract is never hand-written: it is a derived function of data-model.md (typed fields + constraints), the sad.md §6 sequence diagrams (error branches, async actors), and spec.md acceptance criteria. Runs an inline drift check (does the contract match the model and the sequences?) and a reconcile mode. Hard-refuse if data-model.md is missing AND the feature changes the schema → run `data-model {slug}` first; on a legal no-schema-change skip it derives from the existing schema instead.
genkovich · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add genkovich/sdd --skill api技能说明
name: api
model: inherit
effort: medium
agents: []
description: >
Use to derive the API contract for a feature — an OpenAPI 3.1 document at
docs/features/{slug}/contracts/openapi.yaml plus a drift/sync report (and an events doc when
the feature has async flows). Triggers on "api for {slug}", "openapi for {slug}",
"API contract for {slug}", "lock the interface for {slug}", "events for {slug}",
"/sdd:api {slug}", "контракт API для {slug}", "OpenAPI для {slug}", "опиши ендпоінти".
The contract is never hand-written: it is a derived function of data-model.md (typed fields +
constraints), the sad.md §6 sequence diagrams (error branches, async actors), and spec.md
acceptance criteria. Runs an inline drift check (does the contract match the model and the
sequences?) and a reconcile mode. Hard-refuse if data-model.md is missing AND the feature
changes the schema → run data-model {slug} first; on a legal no-schema-change skip it
derives from the existing schema instead.
Skill: api
Projects the upstream artifacts into one interface contract. By default that's an HTTP/OpenAPI contract; this skill is interface-kind aware — and the kind comes from the surface(s) design declared in sad.md frontmatter target_surfaces, read here, not re-derived (→ ../_shared/surfaces.md). For a non-HTTP project it produces the matching contract form (or steps aside):
- HTTP / REST (default) →
contracts/openapi.yaml(OpenAPI 3.1) +api-sync-report.md. - gRPC / RPC → a
.proto(or the repo's IDL) with the same derive-and-drift discipline. - CLI →
contracts/cli.md— the command/flag/exit-code surface derived from the AC. - Library / SDK →
contracts/public-api.md— the public signatures/types the feature exposes. - Event-only / worker → just
contracts/events.md(no request/response surface). - No external interface (pure internal logic) → skip with a one-line note in the report; go straight to
tasks.
Whatever the form, the contract is derived from data-model.md — or, on a legal no-schema-change skip, the existing schema — plus the sad.md §6 sequences + the spec's AC, never typed by hand — generation that diverges from the model or the sequences is the bug this skill exists to catch. The rest of this file details the HTTP path (the common case); the same derive → drift-check → reconcile loop applies to the other forms with the form-appropriate artifact.
This skill keeps only its own machinery. Question phrasing is shared → ../_shared/ask-style.md. Depth (events doc only when async; one resource vs full surface) follows the size matrix → ../_shared/size-matrix.md. The drift-resolution dialog reuses the shared 4-state actions — keep it short, point the machinery to _shared.
Contract summary/description prose follows artifact_language — paths, operationId, status codes and schema names never translate → ../_shared/artifact-language.md.
Owner
Backend Lead (drives the interface). The PM confirms each endpoint maps to a real user story; a frontend / consumer engineer is the first reader — the contract is locked before they start integration.
Inputs
<slug>— same feature slug used by every earlier stage.- Gate (conditional — hard-refuse only when a schema change exists):
docs/features/<slug>/data-model.md. When present, it is the source of typed fields and constraints. When absent, evaluatedata-model's N/A condition (no schema change — size-matrix fast lane) yourself: sad.md §5 declares no new building blocks/entities, no stageddocs/features/<slug>/migrations/, and the spec introduces no new entity → proceed, deriving types/constraints from the existing schema (the livemigrations/DDL +architecture-map.md§Migrations/§Conventions) and saying so loudly in the handoff. Absent and a schema change exists → STOP and point: «rundata-model <slug>first — the contract is derived from its entities». - (Expected)
sad.mdfrontmattertarget_surfaces— picks the contract form (step 1). Absent or empty → warn («surfaces undeclared — re-rundesign, or proceeding asbackend-service») and treat as[backend-service], falling back to the architecture-map derivation (→../_shared/surfaces.md). - (Expected)
docs/features/<slug>/sad.md§6 — the MermaidsequenceDiagramblocks. Theiralt/elsebranches become the errorresponses; an async participant (<message-bus>/<external-system>) on a mutating flow marks its endpointIdempotency-Key-required and seedsevents.md. Absent → note the gap (error branches derived fromspec.md§5 only — likely misses authorization branches) and still generate. - (Expected)
docs/features/<slug>/spec.md— §4 user stories give the endpoint list; §5 acceptance criteria give the shape of each happy + error outcome. The spec deliberately holds no HTTP/status/error-code/SQL detail — that mapping is this skill's job. - (Optional)
docs/features/<slug>/.size— depth hint. Absent → default to M (full surface) and say so loudly in the handoff — «size M (default — no.size; run/sdd:classify-size <slug>)».docs/features/<slug>/adr/*.md— override defaults (versioning, error format, auth scheme) when an ADR mandates it;CONTEXT.md(read both repo-root anddocs/features/<slug>/— per-feature wins →../glossary/SKILL.md) — glossary terms become schema names verbatim. Existingcontracts/openapi.yaml→ diff and update in place, never overwrite whole-cloth.
Protocol
- Gate + interface kind + read.
test -f docs/features/<slug>/data-model.md— a three-way gate, not a binary one:- present → derive from it (the default path below, unchanged);
- absent + no schema change (evaluate `da