跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
法律与合规

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, evaluate data-model's N/A condition (no schema change — size-matrix fast lane) yourself: sad.md §5 declares no new building blocks/entities, no staged docs/features/<slug>/migrations/, and the spec introduces no new entity → proceed, deriving types/constraints from the existing schema (the live migrations/ DDL + architecture-map.md §Migrations/§Conventions) and saying so loudly in the handoff. Absent and a schema change exists → STOP and point: «run data-model <slug> first — the contract is derived from its entities».
  • (Expected) sad.md frontmatter target_surfaces — picks the contract form (step 1). Absent or empty → warn («surfaces undeclared — re-run design, or proceeding as backend-service») and treat as [backend-service], falling back to the architecture-map derivation (→ ../_shared/surfaces.md).
  • (Expected) docs/features/<slug>/sad.md §6 — the Mermaid sequenceDiagram blocks. Their alt/else branches become the error responses; an async participant (<message-bus> / <external-system>) on a mutating flow marks its endpoint Idempotency-Key-required and seeds events.md. Absent → note the gap (error branches derived from spec.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 and docs/features/<slug>/ — per-feature wins → ../glossary/SKILL.md) — glossary terms become schema names verbatim. Existing contracts/openapi.yaml → diff and update in place, never overwrite whole-cloth.

Protocol

  1. 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
阅读完整来源 ↗