API Review

This skill standardizes how to do an API design review (not code style).

Inputs (ask for these if missing)

• Artifact: PR link, diff, branch, or spec.
• API type: CLI / HTTP / library / JSON-RPC / MCP server.
• Target users: internal engineers, external devs, agents, end users.
• Compatibility contract: what must not break (scripts, existing tools, telemetry schemas).

Workflow

1) Identify the API surface

Produce a short inventory:

• Commands/endpoints/methods
• Inputs (flags/body), outputs (stdout/JSON), error shapes
• Auth + session model
• Versioning

2) Pull authoritative guidelines by section (TOC anchor)

When reviewing against a long doc (e.g., “API Design Guidelines”), avoid loading the whole doc.

Rule: retrieve the relevant section by heading anchor, then cite it.

If osgwiki-cli supports TOC + section retrieval (preferred deterministic model):

• osgwiki toc "<Page Title>"
• osgwiki section "<Page Title>" --anchor "#<Heading_Anchor>" --include-children

Interpretation:

• A TOC entry like #Asynchronous_APIs means: return content from that heading until the next same-or-higher-level heading.

If TOC/section retrieval is not available, fall back to manual excerpting with exact headings and quotes.

3) Evaluate with the checklist (severity-tagged)

Classify findings:

• BLOCKER: correctness, security, compatibility breaks
• MAJOR: DX traps, inconsistent semantics, ambiguous naming
• MINOR: polish, docs, consistency

Checklist (apply only what’s relevant):

• Compatibility: breaking changes, deprecation path, migrations
• Naming: consistent, discoverable, stable
• Error model: deterministic, actionable, machine-readable
• Versioning: schema versions, endpoint evolution strategy
• Observability: logs, traceability, correlation ids, exit codes
• Security: auth boundaries, injection, path traversal, secrets
• Determinism: same inputs => same outputs (esp for agents)
• Ergonomics: defaults, progressive disclosure, “pit of success”

4) Output as a review comment/report

Use this structure:

API Review Summary

• Verdict: approve / approve-with-nits / request-changes
• Top 3 issues (one-liners)

Surface Inventory

Findings

• BLOCKER: … (include fix)
• MAJOR: …
• MINOR: …

Guideline Citations

• § (anchor #...) — short quote

Suggested shape

• Example request/response / CLI usage
• Proposed error payload

Notes

• Prefer deterministic behaviors over “smart” heuristics for agent-facing APIs.
• Don’t bikeshed implementation details. Focus on the contract.