Authoring Api Spec

authoring-api-spec — SKILL.md

> Variant: standard · When to use: authoring the engineering wire contract of an API surface — to a bar where a client integrates and a server implements from the contract alone, with no ambiguity about shapes, errors, or auth.

Overview

This skill is the how-to of writing a strong API specification — the engineering wire contract of an API surface. It says what each operation looks like over the wire: the request and response shapes (fields, types, required/optional, constraints), the auth model, the error model, and worked examples. This skill carries the producer's judgment — the research method and the quality bar — not the section list. It assumes two collaborators: an api-spec template tool that supplies the section structure, and a deep-research capability to ground the contract in established API-design practice. The producer is handed the upstream feature-spec (the behaviors the API must expose) and, where present, the architecture-doc (service boundaries) and the data-model (the entities resources map to) — never a blank page. The bar to clear: the contract is implementable and callable — a client engineer can call every operation correctly and a server engineer can implement it without asking the author, with no ambiguity about shapes, errors, or auth.

When to activate

• Authoring an API specification from an approved feature-spec that names the behaviors an API must expose.
• Specifying the operations, request/response schemas, auth, error model, and examples of an API surface (REST, GraphQL, or RPC/gRPC).
• Filling an api-spec template with researched, decision-complete, fully-typed per-operation content.
• Amending an approved api-spec as a versioned delta (a new/changed operation, a field added/removed, a parameter made required, an operation retired) — see Step 6.

Do NOT activate when:

• Designing the persistence data-model (stored entities + relationships) → that is a separate concern and is upstream here. The api-spec describes wire DTOs and references the data-model; a DTO is not a stored row.
• Writing the published, consumer-facing API reference (the prose docs end-users read, often generated from this contract) → that is a separate downstream document with a different audience.
• Writing the implementation / architecture (how the service behind the endpoints is built) → that is the design layer, not the interface.
• Reviewing or grading a finished api-spec → use reviewing-api-spec (the dedicated gate, single-sourced with this skill's Step-7 bar); this skill is produce-side only.
• Authoring the feature-spec itself (the behaviors) → that is upstream input here.

Inputs

Read every document the plan hands you — your depends_on set (the upstream documents discovery determined inform this one) — and trace this document's content back to them. Do not assume a fixed input: the typical upstreams this skill names are method guidance, not a cap on what you receive. Be self-contained — produce the document from whatever context you actually receive; when an expected informing document is absent, proceed on what you have and surface the gap as an explicit assumption, never fabricate to fill it. And use a research capability where one is available (deep-research) to make the document comprehensive and exhaustive, not merely to fill the template.

Capability context (when provided): If a capability_record (a record from capability-map.yaml product_capabilities) is injected by the caller, read it before Step 1. It defines your scope boundary: owns = entities you cover; refs = entities you reference but do not own; publishes/consumes = events you surface; entry_points/exit_points = how users arrive and leave; has_ui/has_api/has_persistence = which surfaces apply. When present, treat it as a hard constraint — do not stray outside the boundary it defines.

Workflow

Step 1: Take the structure from the template tool — don't invent an outline

Get the section structure from your api-spec template tool (comprehensive variant). Do not restate or re-derive a section list here; this skill supplies the method that fills those sections well. If no template is available, obtain a comprehensive api-spec structure (request/forge one, or fall back to the canonical set: API overview, operation list, per-operation request+response, shared data types, auth+authorization, error model, pagination/filtering/rate-limits, examples, open questions), then proceed.

If a capability_record is present: expose entry_points as API operations; include async operations for publishes/consumes events; mark refs fields as read-only cross-capability references.

Step 2: Pick the API style first — then apply the same rigor in that style's notation

A project uses one API style. Choose it, then render the contract in that style's notation — but the rigor (typed schemas, complete errors, auth, examples) is identical across all three:

• REST → OpenAPI/JSON-Schema conventions: endpoint tables (method + path), typed parameters and request bodies, responses keyed by HTTP status, reusable schemas, declared security schemes.
• GraphQL → SDL: typed object/scalar/enum/input types, Query/Mutation/Subscription root fields, errors in the top-level errors array.
• RPC / gRPC → proto service/rpc method signatures with typed request and response messages and status codes.

Do not mandate OpenAPI for a non-REST project — OpenAPI is the REST flavor, not the only format. The skill teaches contract rigor for whichever style the project uses.

Step 3: Load the upstream docs; drive coverage off the feature-spec

Read the approved feature-spec and any upstream context (architecture-doc, data-model) — this is your input, not a blank page. The feature-spec's behaviors are your operation-coverage checklist: every behavior the API must expose becomes one or more operations; every operation traces back to a behavior (no orphan/invented endpoints). Map each resource onto the data-model's entities by reference — note where the wire DTO differs from the stored entity (computed, derived, or omitted fields); do not duplicate or contradict the data-model. Where the upstream is thin, make the gap an explicit open question or stated assumption, never a silently-invented shape.

Step 4: Research to ground the contract

Use a deep-research pass to ground the contract in established API-design practice — REST/HTTP semantics and status codes, JSON-Schema/OpenAPI rigor, GraphQL SDL, RPC/gRPC, consistent naming, error modeling (e.g. RFC 9457 Problem Details for REST), versioning, and auth patterns — for this product's surface, not "API specs in general." If no research capability is available, do NOT fabricate field names, limits, status codes, or error codes — state them as explicitly-flagged assumptions to validate before build.

Step 5: Apply the per-section method

Fill the template's sections to this method. Collapse a section a thin API doesn't need; size proportionally.

• API overview — state the style + transport, the base URL/endpoint, and a concrete versioning scheme (URL path /v1 is least ambiguous and most common — major-version only per AIP-185; plan versioning from the start). State naming + date/time conventions once, here.
• Versioning policy — classify changes + plan retirement (state it day-one). State what counts as a breaking change: additive = a new optional field/operation/enum-value the tolerant-reader client ignores (clients must ignore unknown response fields); breaking = removal/rename/type-narrowing/required-add/default-change/semantic-shift (AIP-180 source/wire/semantic). And state the deprecation → sunset lifecycle for a removal: Deprecation (RFC 9745, the date it became deprecated) → a migration window → Sunset (RFC 8594, the date it may stop responding; Sunset ≥ Deprecation) + a published migration path. The policy is stated here; the act of deprecating a specific operation during a change is Step 6 (amend).
• Resource / operation list — one row per operation up front (method+path / root field / Service.Method) so the surface is scannable before the per-operation detail.
• Per-operation request + response — fully typed on both sides. Every parameter/argument/field carries a type, a required/optional flag, and constraints (length, enum, format, range). Every response is keyed to a status code (or gRPC status / GraphQL data-vs-errors) with its body schema. Choose the status deliberately — 201+Location for a create, 204 for a no-body success, 401 (unauthenticated) vs 403 (forbidden/insufficient-scope) not conflated, 409 for a conflict, 422/400 for validation; not 200 for everything. An operation specified only on the happy path is not done.
• Shared data types — define each reusable DTO once and reference it by name ($ref / SDL type / proto message); never inline-redefine the same shape across operations. These are wire types — where a DTO projects a stored entity, reference the data-model, do not restate it.
• Auth + authorization — name the scheme(s) (API key / OAuth 2.0 + which flow — auth-code+PKCE for user-facing/public clients, client-credentials for service-to-service / JWT / mTLS), where the credential goes, and the authorization model: every non-public operation names its required scope/role, mapped to the operation list's auth-scope column ("authenticated" without a per-operation scope is under-specified). State token lifecycle + HTTPS + no secret in a URL.
• Error model — the catalog, not just the happy path. Define one consistent error shape for the whole API (e.g. RFC 9457 Problem Details for REST; an errors array for GraphQL; google.rpc.Status for gRPC) carrying a machine-readable code (the client branches on it — the HTTP status is too coarse), a human message (for logs, not end-user display), and a request/trace id. Then enumerate every named failure case per operation (validation, auth, forbidden, not-found, conflict, rate-limited, server) with its status code and its retryability (429/5xx retryable after Retry-After with backoff; 4xx not — retrying won't help). This is the single most-skipped part of an api-spec — do it deliberately.
• Pagination / filtering / sorting / rate-limits — for collection operations, pick a pagination strategy (cursor-based for large/dynamic/user-facing; offset for small/static), define the request params + the response envelope (next-cursor / has-more / Link header) + default/max page size; list filterable + sortable fields with a stable tie-breaker; state rate limits + the headers + the 429 behavior.
• Worked examples — at least one full request/response pair per primary operation, consistent with the schemas (same field names, types, status codes). An example that contradicts its schema is a defect.

Step 6: Amending an approved contract (the delta case)

When the contract already exists and a change is requested — edit the delta, don't redraw. Scope = the touched operations + their request/response schemas + the shared types + the error cases on them (+ the versioning section if the change is breaking). Then:

1. Classify the change — additive vs breaking. Additive (a new optional field, a new operation, a new optional response field a tolerant-reader ignores, a new optional error case) ships in-version. Breaking (a removed/renamed field or operation, a type narrowing, an optional field made required, a default/semantic change, a removed enum value) does not edit in place under the same version. A breaking change shipped as a minor in-version edit silently breaks every live client — the cardinal amend defect.
2. A breaking change is a versioning event, not an edit. Route it to a new version (/v2, a new date-pin) and put the old surface through the deprecation → sunset lifecycle (Deprecation → a migration window → Sunset, Sunset ≥ Deprecation) with a migration guide (old→new mapping). Never silently mutate or delete the old operation.
3. Analyze backward/forward compatibility — backward: the existing version keeps working; forward: new fields optional/defaulted, enum additions tolerated, an operation never silently changing meaning.
4. Version + changelog the delta — bump the document's own version (the §10 revision history, distinct from the API version) + a changelog entry (additive/breaking); mark retired operations deprecated, not silently deleted.
5. Flag the forward/downward ripple — the change ripples to the downstream api-reference (re-synced/re-generated from the changed contract + the deprecation markers), the implementation + test-plan building against it, the live clients (the reason for the sunset window), and the release-runbook; the upstream feature-spec is amended first (a new behavior drives the new operation). Name the ripple; don't leave it for a downstream reader to discover.

A greenfield first contract skips Step 6 (no prior version to amend).

Step 7: Self-check against the no-ambiguity bar before handing off

Confirm all hold (this is the bar a runtime review gate — reviewing-api-spec — asserts; author and gate share it so they don't drift):

1. Style + base + versioning stated — the API style, base URL/endpoint, and a concrete versioning scheme are present; the breaking-vs-non-breaking change rule + the deprecation→sunset policy are stated.
2. Every operation listed + traced — the operation list is complete; each operation maps to an upstream feature-spec behavior (no orphan/invented endpoints, none missing).
3. Every operation fully typed on both sides — request and response fully typed, each field required/optional with constraints, every response keyed to a status code. A happy-path-only operation fails.
4. Auth + per-operation authorization — authentication scheme(s) (+ OAuth flow per client type) stated; every non-public operation names its required scope/role; token lifecycle + HTTPS; nothing implicitly open.
5. Error model complete — one consistent error shape (machine code + message + request id) and every named failure case enumerated per operation with its retryability. A spec listing only 2xx responses fails.
6. Shared types defined once + referenced — reusable DTOs defined once and referenced; wire types reference the data-model rather than restating/contradicting it.
7. Pagination/rate-limits specified — collection operations define pagination; rate limits + headers stated.
8. Examples present + consistent — at least one request/response pair per primary operation, matching the schemas exactly.
9. Naming + versioning consistent — applied uniformly across the surface.
10. Grounded, honest & one-directional — operations/shapes reflect the feature-spec + data-model (not fabricated; gaps surfaced as assumptions/open-questions, not invented); one-directional vs the api-reference (this contract is the published reference's source of truth — never reverse-engineered from it); where a live API exists, claims about current operations/shapes are consistent with the shipped surface (greenfield: N/A).
11. (Amend only) delta well-scoped + classified + versioned — on a change request: the changed operations meet 1–10 on what they touched; the change is classified additive/breaking; a breaking change carries a new version + the deprecation→sunset plan + a migration guide; backward/forward compatibility analyzed; the forward/downward ripple flagged; the document version bumped + a changelog; retired operations marked deprecated, not deleted. On a greenfield fir

…

Source & license

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

• Author: bm629
• Source: bm629/agent-skills
• License: MIT

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