api-review
Scannednpx machina-cli add skill rana/yogananda-skills/api-review --openclawRead all project markdown documents to ground in the project's actual state.
API & Data Model Review
Evaluate for consistency and idiom:
API Surface
- REST endpoint naming: consistent, predictable, resource-oriented?
- Response shapes: envelope conventions followed? Pagination consistent?
- Error formats: uniform across all endpoints?
- Versioning: applied consistently?
- Field naming: camelCase/snake_case consistent? Abbreviations standardized?
Data Model
- Table/column naming conventions consistent?
- Foreign key relationships complete and documented?
- Migration strategy clear?
- Index strategy specified for query patterns?
Design Rationale
- Is the "why" explained, not just the "what"?
- Would a new developer understand the design choices from the docs alone?
- Are there design decisions that should be ADRs but aren't?
Idiom
- Does the API follow established conventions for its domain?
- Are there modern (2026) patterns that would improve the design?
- Is the API discoverable? Self-documenting?
Focus area: $ARGUMENTS
For every finding:
- The inconsistency or improvement
- The specific location (endpoint, table, section)
- The proposed fix
Present as an action list. No changes to files — document only.
Output Management
Hard constraints:
- Segment output into groups of up to 10 findings, ordered by inconsistencies over style preferences.
- Write each segment incrementally. Do not accumulate a single large response.
- After completing each segment, continue immediately to the next. Do not wait for user input.
- Continue until ALL findings are reported. State the total count when complete.
- If the analysis surface is too large to complete in one session, state what was covered and what remains.
What questions would I benefit from asking?
What am I not asking?
Source
git clone https://github.com/rana/yogananda-skills/blob/main/skills/api-review/SKILL.mdView on GitHub Overview
Reviews REST endpoints and data models for consistency, idioms, and readability. It checks endpoint naming, response shapes, error formats, versioning, and pagination, and assesses data model naming, FK documentation, and migrations. Grounded in project markdown and ADRs to clarify the why behind design choices and to help future developers understand the rationale.
How This Skill Works
Reads project markdown docs to ground the current state and evaluates API Surface, Data Model, and Design Rationale for consistency and idiom. For each finding, it records what is inconsistent, where it occurs, and a concrete proposed fix. Findings are emitted in segments of up to 10 items, ordered by impact, with progress notes on what remains if the surface is large.
When to Use It
- Review REST endpoint naming for consistency and resource orientation.
- Validate response envelope shapes and pagination patterns across endpoints.
- Audit error formats and versioning to ensure uniformity.
- Assess data model naming, foreign keys, and migration strategies.
- Check discoverability and design rationale documentation (ADR’s).
Quick Start
- Step 1: Gather project markdown docs and set the focus area (REST endpoints or data model).
- Step 2: Run the API & Data Model Review to identify inconsistencies and gather findings.
- Step 3: Produce action items segmented by up to 10 findings with locations and fixes.
Best Practices
- Start with API Surface checks (endpoints, responses, errors, versioning) before data model checks.
- Enforce consistent field naming (camelCase vs snake_case) across all endpoints.
- Document the rationale for design decisions with ADRs and add missing ones.
- Attach location and a concrete proposed fix to every finding.
- Segment findings into batches of 10 and report remaining findings after each pass.
Example Use Cases
- Inconsistent endpoint naming e.g. /users vs /user for the same resource.
- Pagination metadata missing or inconsistent across list endpoints.
- Non-uniform error payloads across endpoints.
- Missing or undocumented foreign key relationships in data models.
- Field naming drift between API responses and database columns.
