documenting-contracts skill (riekelt) for Claude Code: document APIs, payloads and webhooks

Makes Claude document an HTTP API, message queue, webhook or file format for callers who cannot see the code, field by field.

Installs: 20.1K; on skills.sh
Stars: 36; on GitHub
Updated: Sep 2026; last repo commit

documenting-contracts has Claude document the wire, not the implementation: wire types, required as yes, no or conditional, and omitted versus null stated wherever it matters. Detail lives at four levels (index, semantics, shape, example) and each DTO is defined once in a catalog with a source line. When an OpenAPI or AsyncAPI spec exists, that spec owns the field tables. It lists technical-writing as required background.

Good for

Backend developers writing an API reference for other teams
Teams documenting webhooks, queues or file formats
Anyone writing the api-reference of a legacy-codebase docs tree

Install documenting-contracts

Claude Code

Copy this prompt.

Install the documenting-contracts skill in Claude Code. Run this command:

/plugin marketplace add riekelt/technical-writer
/plugin install technical-writer@technical-writer

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both, or you get every skill twice. The skills CLI route must include technical-writing, which documenting-contracts lists as REQUIRED BACKGROUND in its SKILL.md.

From the project README. Source.

What's in the skill

When it loads

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".

Sections in SKILL.md

Overview
When to invoke, and not
One home versus generated specs
The four detail levels
The DTO catalog
The template
Conventions
Endpoints
POST /thing
Messages
thing.create
Commands
<command>
DTOs
ThingRequest
Thing

Key facts

Author: riekelt (owner of the GitHub repo)
License: MIT (LICENSE file and plugin manifest)
Installs on skills.sh: 20,134 as of 2026-11-02
GitHub stars: 36 for the whole riekelt/technical-writer repo, 2026-11-02
What is inside: 1 file: SKILL.md
Needs: The technical-writing skill (SKILL.md lists it as REQUIRED BACKGROUND)
Part of: The technical-writer plugin: 11 skills, 2 agents and 2 commands
Last repo commit: 2026-09-13
Works in: Claude Code per the README install section. The repo also ships Codex and Cursor plugin manifests.

What it includes

A generated spec owns the field tables
When an OpenAPI or AsyncAPI spec exists, the markdown covers only what the spec cannot say and links to the spec.
Read · One home versus generated specs
Index, semantics, shape and example, each in its own place
Tables list what exists, prose covers side effects and quirks, the DTO catalog holds fields, and at most one example per DTO. Repetition across levels is the defect to hunt.
Write · Four detail levels
One field table per DTO with wire types and a source line
Types describe what crosses the wire, required is yes, no or if-condition, enums get their own table, and constraints are written in domain terms read from validation the code enforces.
Try: “Document the /orders endpoints and their request and response payloads.”
Write · DTO catalog
Conventions, endpoints, messages, commands, DTOs, errors
Six sections: Conventions, Endpoints, Messages, Commands, DTOs and Errors. Endpoint and message sections hold semantics only.
Write · Template
Check the serializer, document asymmetries, errors once
The wire is what the configured serializer emits, so Claude reads that configuration first. Examples are illustrative, and endpoint and DTO counts are recorded as denominators.
Read · Rules

From the official docs

Permissions

Low risk

Claude reads your API code to document it. Use it on code you may share with your AI provider.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It reads your API source
SKILL.md has Claude read DTOs, validation and the serializer configuration before writing any field row. Our advice: use it on code you are willing to send to your AI provider. github.com
The plugin route adds 2 agents and 2 commands
The plugin ships agents prose-reviewer and doc-grounder (both with Read, Glob, Grep and Bash tools) and the commands /prose-review and /ground-docs. The plugin folder has no hooks or MCP config. Use the skills command in the install box if you want only this skill. github.com

Technical details

Turning on read-only	No read-only mode. The skill tells Claude to write or edit documents.
Sign-in and keys	SKILL.md names no account or API key.
Data retention	SKILL.md names no logging or telemetry.
Scopes	Claude reads API code and serializer configuration Writes an api-reference document in your repo

Questions

What does documenting-contracts do?

It makes Claude write exhaustive reference documentation for anything machines call or parse, such as REST endpoints, queue messages, webhooks, CLI commands and file formats.

How do I install documenting-contracts?

Use the install box at the top of this page. The plugin route installs the whole set. The skills command route names technical-writing as well, because this skill lists it as required background.

Does it generate an OpenAPI file?

No. SKILL.md says writing a machine spec is not this document's job. If one exists it owns the field tables and the markdown links to it.

Why does it read my serializer config?

SKILL.md says 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 a DTO.

documenting-contracts vs documenting-legacy-codebases?

The api-reference of a legacy campaign is this skill's document. The legacy skill handles the survey, evidence and ledger. This one handles how endpoints, messages and payloads are written.

Is documenting-contracts safe to install?

The skill folder holds only SKILL.md, so it bundles no scripts. Claude reads your API code and serializer configuration to document it. Review the changes it makes to your documents, as you would any edit.

Can I use documenting-contracts in the Claude app or Cursor?

The README documents Claude Code, and the repo also ships Codex and Cursor plugin manifests. It does not mention the Claude app. Our advice: this page offers no Claude app upload because the skill works on documents inside a repository, so use Claude Code or Codex.

Information

updated Nov 2, 2026

Repository: riekelt/technical-writer
Folder: plugins/technical-writer/skills/documenting-contracts

riekelt/technical-writer skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

README · github.com
marketplace.json · github.com
documenting-contracts on skills.sh · skills.sh
SKILL.md · github.com
LICENSE · github.com
documenting-legacy-codebases SKILL.md · github.com