documenting-contracts
Use when documenting an HTTP API, message payloads, queue contracts, DTOs, file formats, or webhooks - or when writing the api-reference of a legacy campaign, or when callers keep asking what a field means or which errors an endpoint returns. Encodes the four detail levels, the DTO-first catalog, wire types with source anchors, the generated-spec one-home rule, and omitted-versus-null semantics. Use whenever a machine interface needs documenting for its callers, even if nobody says "API docs".
- Installs
- 18.1K
- Last 24h
- +417
- Trending rank
- #737
- Security
- Pass
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/riekelt/technical-writer --skill documenting-contracts- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads documenting-contracts automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
Documenting contracts
REQUIRED BACKGROUND: the technical-writing skill (hard rules, truth rules, style).
Overview
A contract document is read by a stranger who cannot see the code and is about to depend on it. Core principle: document the wire, exhaustively, with each detail at its own level; the caller's language is the wire format and domain terms, never the implementation's types. Contract surfaces are reference kind, so the core Reference rule applies: every endpoint, every field, every error.
When to invoke, and not
Invoke when documenting anything machines call or parse: REST and RPC endpoints, message queues and topics, webhooks, CLI commands, file formats. The api-reference.md of a legacy campaign (documenting-legacy-codebases) is this skill's document. Do NOT invoke for internal code interfaces, which the code documents itself, or for configuration references, which belong in config-reference.md under the core Reference rule. Judging whether the contract is well designed is out of scope: this skill documents the contract that exists.
One home versus generated specs
When an OpenAPI or AsyncAPI spec exists, or the code generates one, that spec owns the field tables. The markdown then documents only what the spec cannot say (semantics, side effects, ordering, omitted-versus-null) and links the spec; never hand-maintain field tables beside a generated one; a second home drifts. The catalog below is for the case where no machine spec exists; writing one is not this document's job.
The four detail levels
Each level has its own home; the writer moves detail found at the wrong level into the level that owns it:
| Level | The caller asks | Home |
|---|---|---|
| Index | What exists here | The endpoint, message, and command tables |
| Semantics | What invoking it does | Per-endpoint, per-message, and per-command prose: side effects, events published, idempotency, redelivery, exit behavior, quirks |
| Shape | What crosses the wire | The DTO catalog: one field table per DTO |
| Example | What it looks like | At most one illustrative example per DTO |
Repetition across levels is the defect to hunt: an endpoint section restating its DTO's fields, an example smuggling in a field the table lacks.
The DTO catalog
A DTO is defined once and referenced everywhere:
- Wire types, not language types.
string (date, ISO 8601),number (64-bit integer),string (decimal): the column says what crosses the wire, complete enough that no reader needs the implementation's type as a proxy. A 64-bit integer that exceeds the range or precision of a consumer's native number type is wire information; the type name that produced it is not. - One Source line per DTO, naming the owning class or schema file. Reference kind sanctions this evidence anchor, as a config reference carries binding evidence.
- Required is a tri-state:
yes,no, orif <condition>with the condition stated. - Omitted versus null is stated wherever it matters, and always on a DTO used in a replace-style write, where an omitted field is absent from the result. Where the server assumes a value on omission instead, that value goes in the Default column.
- Enums get their own table, values with meanings; nested objects link to their own catalog entry, never a second inline copy.
- Constraints in domain terms: "past date", "1..100 chars", "must reference an existing budget policy", read from validation the code enforces.
The template
# API reference: <service>
## Conventions
[Once, never per endpoint: base path, auth, content type, the error
envelope, global (de)serialization behavior, idempotency defaults.]
## Endpoints
| Method | Path | Purpose | Request | Response | Errors |
|---|---|---|---|---|---|
| POST | `/thing` | Create a thing | [ThingRequest](#thingrequest) | 200 [Thing](#thing) | 422, 404 |
### POST /thing
[Semantics only: side effects, events published, idempotency, quirks.
No field lists; the index and catalog are not repeated.]
## Messages
| Direction | Destination | Payload | Reply | On error |
|---|---|---|---|---|
| in | `thing.create` | [ThingRequest](#thingrequest) | `thing.created` | `thing.create.error` |
### thing.create
[Semantics only: redelivery, ordering, events published, quirks;
what differs from the sibling transport is called out here.]
## Commands
| Command | Purpose | Arguments | Output |
|---|---|---|---|
### <command>
[Semantics only: side effects, idempotency, exit behavior, quirks.]
## DTOs
### ThingRequest
Source: `api/ThingRequest`
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
[Omitted versus null, where it matters. At most one illustrative example.]
### Thing
[Response shapes are catalog entries like any other.]
## Errors
| Status | When | Body |
|---|---|---|
Rules
- Verify against the serializer, not the class. The wire is what the configured serializer emits and accepts: a global trimmer, a null-omitting mapper, or a custom date format changes the contract without touching any DTO. Read the serialization configuration before writing a single field row.
- Asymmetries are semantics. The mutation that publishes an event on one transport and nothing on the other, or the endpoint that skips a step its siblings perform, is documented at the semantics level.
- Examples are illustrative, never normative. One per DTO at most, labeled so, and containing no field the table lacks; the table is the contract.
- Errors are cataloged once, as envelope plus a status table; an endpoint lists only which entries apply to it. Command failures are cataloged the same way, by exit code.
- The exhaustiveness is checkable. The endpoint count and the DTO count are denominators like any other (core truth rules): a legacy campaign records them in its coverage ledger with the commands behind them and the date.
FAQ
What does the documenting-contracts skill do?
Use when documenting an HTTP API, message payloads, queue contracts, DTOs, file formats, or webhooks - or when writing the api-reference of a legacy campaign, or when callers keep asking what a field means or which errors an endpoint returns. Encodes the four detail levels, the DTO-first catalog, wire types with source anchors, the generated-spec one-home rule, and omitted-versus-null semantics. Use whenever a machine interface needs documenting for its callers, even if nobody says "API docs".
How do I install documenting-contracts?
Run npx skills add https://github.com/riekelt/technical-writer --skill documenting-contracts in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/documenting-contracts/ (personal) or .claude/skills/documenting-contracts/ (project).
Which AI agents can use documenting-contracts?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is documenting-contracts safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains documenting-contracts?
It is published by riekelt in riekelt/technical-writer. It has 18,112 recorded installs.
More from riekelt/technical-writer
technical-writing
riekelt/technical-writer
Use when writing, restructuring, or revising any technical document - specs, design docs, READMEs, reference documentation, plans, reports - or any prose that must survive being read twice by someone in a hurry. Encodes the house style, the truth and sourcing rules, and the banned-constructions list. Use whenever you produce repository-bound text longer than a paragraph, even if nobody says "document". Foundation for the sibling document-type skills.
reviewing-technical-prose
riekelt/technical-writer
Use when reviewing, rewriting, or editing someone else's technical text, when writing a review report on a document, or as the final check before delivering any document. Encodes the severity mapping, the findings format, the what-not-to-flag list, and the delivery checklist. Use before any document ships, even when it looks fine.
writing-design-docs
riekelt/technical-writer
Use when writing a proposal, RFC, design document, spec, or migration plan - anything that argues for a change, records a design, or asks readers for input on one. Encodes the proposal skeleton, the Why & What decision box, and the completeness checks. Use whenever a change needs arguing or scoping in writing, even if the user just says "write up the approach".
writing-runbooks
riekelt/technical-writer
Use when writing operational documentation - runbooks, setup guides, release procedures, migration guides, deprecation guides, troubleshooting entries, or any ordered procedure someone will execute under time pressure. Encodes the runbook skeleton, the risk legend, the symptom-first troubleshooting format, and the migration-guide rules (mapping table, mandatory rollback, deprecation dates, built-in expiry). Use whenever someone will execute the text, even if it is called a "guide" or "setup notes".
writing-changelogs
riekelt/technical-writer
Use when writing a changelog entry, release notes, or a "what shipped" summary after completing work. Encodes the entry shape, the handover template, and the honesty conventions. Use after shipping meaningful work, even if the user just says "summarize what we did".
writing-postmortems
riekelt/technical-writer
Use when writing a postmortem, incident report, or root-cause analysis after an outage, a defect that reached users, a data issue, or a near miss - or when turning an incident channel, alert log, or war-room thread into a durable document. Encodes the blameless framing, the evidence-only timeline, contributing factors, and owned action items. Use whenever something broke and the write-up must outlive the incident.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.