api-review
Scannednpx machina-cli add skill athola/claude-night-market/api-review --openclawAPI Review Workflow
Table of Contents
Usage
Use this skill to review public API changes, design new surfaces, audit consistency, and validate documentation completeness. Run it before any API release to confirm alignment with project guidelines.
Required Progress Tracking
api-review:surface-inventoryapi-review:exemplar-researchapi-review:consistency-auditapi-review:docs-governanceapi-review:evidence-log
Workflow
Step 1: Surface Inventory
Catalog all public APIs by language. Record stability levels, feature flags, and versioning metadata. Use tools like rg to find public symbols (e.g., pub in Rust or non-underscored def in Python). Confirm the working tree state with git status before starting.
Step 2: Exemplar Research
Identify at least two high-quality API references for the relevant language, such as pandas, requests, or tokio. Document their patterns for namespacing, pagination, error handling, and structure to serve as a baseline for the audit.
Step 3: Consistency Audit
Compare the project's API against the identified exemplar patterns. Analyze naming conventions, parameter ordering, return types, and error semantics. Identify duplication, leaky abstractions, missing feature gates, and documentation gaps.
Step 4: Documentation Governance
Validate that documentation includes entry points, quickstarts, and a complete API reference. Verify that changelogs and migration notes are maintained. Check for SemVer compliance, stability promises, and clear deprecation timelines. Confirm that documentation is generated automatically using tools like rustdoc, Sphinx, or OpenAPI.
Step 5: Evidence Log
Record all executed commands and findings. Summarize the final recommendation as Approve, Approve with actions, or Block. Include specific action items with assigned owners and due dates.
API Quality Checklist
Naming
Confirm consistent conventions and descriptive names that follow language-specific idioms.
Parameters
Verify consistent ordering and ensure optional parameters have explicit defaults. Check that type annotations are complete.
Return Values
Analyze return patterns for consistency. Confirm that error cases are documented and that pagination follows a uniform structure.
Documentation
Verify that all public APIs include usage examples and that the changelog reflects current changes.
Output Format
The final report must include a summary of the API surface, a numerical inventory of endpoints and public types, and an alignment analysis against researched exemplars. Document consistency issues and documentation gaps with precise file and line references. Conclude with a clear decision and a timed action plan.
Technical Integration
Use imbue:evidence-logging for reproducible command capture and imbue:structured-output for formatting findings. Reference imbue:diff-analysis/modules/risk-assessment-framework when assessing breaking changes.
Module Reference
- See
modules/surface-inventory.mdfor API cataloging patterns - See
modules/exemplar-research.mdfor researching API standards - See
modules/consistency-audit.mdfor cross-API consistency checks
Troubleshooting
If the audit command is missing, verify that dependencies are installed and accessible in the system PATH. Check file permissions if access errors occur. Use the --verbose flag to inspect execution logs if the tool behaves unexpectedly.
Source
git clone https://github.com/athola/claude-night-market/blob/master/plugins/pensive/skills/api-review/SKILL.mdView on GitHub Overview
api-review evaluates the public API surface and design to ensure consistency with project guidelines. It audits naming, parameters, return types, and documentation governance while researching exemplar patterns. Note: it is not intended for architecture reviews or bug fixes.
How This Skill Works
It follows a five-step workflow: surface inventory, exemplar research, consistency audit, documentation governance, and evidence logging. It uses tools such as surface-analyzer, exemplar-finder, and consistency-checker, and records findings with imbue:evidence-logging. The final output is a recommendation plus an actionable plan.
When to Use It
- Before releasing public APIs to ensure design alignment with guidelines
- During API design reviews to audit naming, parameter order, and return types against exemplars
- When auditing consistency across the API surface
- When governing documentation, changelogs, and migration notes
- When creating an evidence log to support a final approval decision
Quick Start
- Step 1: Surface Inventory: Catalog all public APIs by language, record stability levels, feature flags, and versioning metadata; verify git status with git status.
- Step 2: Exemplar Research: Identify at least two high-quality API references and document patterns for namespacing, pagination, error handling, and structure.
- Step 3: Consistency + Docs Governance + Evidence: Compare against exemplars, validate docs (entry points, quickstarts, API reference), and log findings; finalize with a recommendation and action items in the evidence log.
Best Practices
- Catalog the surface inventory with language, versioning, and stability metadata
- Identify at least two high-quality exemplars and document baseline patterns
- Compare naming, parameter ordering, return types, and error handling against exemplars
- Validate documentation includes entry points, quickstarts, API reference, and changelog
- Record all commands and findings in the evidence log and produce a clear final recommendation
Example Use Cases
- Auditing a Python client library’s public API surface before a major release
- Aligning a Rust crate’s surface with Tokio-like naming, pagination, and error handling patterns
- Ensuring OpenAPI/open-source docs are generated automatically and consistent with rustdoc or Sphinx
- Documenting deprecations, SemVer promises, and migration notes in the changelog
- Generating an evidence log and action items for stakeholders prior to approval
