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.

Do NOT activate when: