apirev-documentlisted
Install: claude install-skill vivekbhange-hub/api-reverse-skill
# apirev-document: from inferred spec to docs a teammate can use
An inferred spec is accurate about shape and silent about meaning. This skill adds the meaning,
carefully: names and descriptions come from the field names, example values and the user's
knowledge, and anything that is a guess says so. The spec stays honest; the README becomes the
page a new teammate reads first.
## Inputs
- `api/openapi.json` and `api/inference-report.md` from `apirev-infer`.
- Optional: anything the user knows about the domain (glossary, a Slack thread, old docs).
- Commands below say `python3`; on Windows use `python` (or `py -3`).
## Outputs
- `api/openapi.json` (and `api/openapi.yaml`) updated in place, after the user approves the
changes.
- `api/README.md`: human documentation.
## Steps
1. **Read the report first, then the spec by path.** Note every low-confidence finding; they
decide where you must write "inferred" or "unverified".
2. **Draft spec edits as a list before writing anything.** For each operation, propose:
- `operationId`: keep the generated one unless it is unclear (`postAuthLogin` -> `login`).
Keep them unique and camelCase; SDK method names come from them.
- `summary`: one line, imperative, under 60 characters ("List pets, newest first" only if the
samples show the order; otherwise "List pets").
- `description`: what it does, then known caveats. Keep the generated sentence "Inferred from
N recorded requests." so readers see the evidence.