{"manifest":{"name":"API Contract Reviewer","version":"1.0.0","description":"Review an API design for REST compliance, consistency, security, breaking changes, and developer experience. Accepts OpenAPI specs, markdown endpoint lists, or plain descriptions.","tags":["api","openapi","rest","review","design","security"],"standard":"agentskills.io","standard_version":"1.0","content_checksum":"85a836e7678e053fd93e10659c090be07b6c7421faff9328b40948ffc31ad3fa","bundle_checksum":null,"metadata":{},"files":[]},"files":{"SKILL.md":"# API Contract Reviewer\n\n> **Purpose:** Review an API design — REST endpoints, OpenAPI spec, or informal description — for consistency, REST principle adherence, security posture, breaking change risk, and developer experience quality. Catches design mistakes before they become permanent.\n\n---\n\n## Invocation\n\n```\n/api-review \n```\n\n**Accepts:**\n- OpenAPI YAML or JSON\n- Markdown list of endpoints\n- Plain English description of the API\n\n---\n\n## Review Dimensions\n\n### 1. REST Compliance\n\n- HTTP verbs used correctly?\n - `GET` = read, safe, idempotent\n - `POST` = create or non-idempotent action\n - `PUT` = full replace, idempotent\n - `PATCH` = partial update, idempotent\n - `DELETE` = remove, idempotent\n- Resource names are nouns, not verbs (`/users` not `/getUsers`)\n- Nested resources used appropriately (`/users/{id}/orders` vs `?user_id=`)\n- Status codes appropriate: 201 (created), 204 (no content), 400 (bad request), 401 (unauth), 403 (forbidden), 404 (not found), 409 (conflict), 422 (validation), 429 (rate limit)\n\n---\n\n### 2. Consistency Audit\n\n- Naming convention: consistent across all endpoints? (camelCase vs snake_case vs kebab-case)\n- Pagination: consistent style on all list endpoints? (cursor vs offset, same field names)\n- Error response shape: same structure everywhere?\n- Date format: ISO 8601 throughout? (`2026-02-20T00:00:00Z`)\n- ID format: UUID vs integer vs slug — consistent?\n- Envelope style: `{ data: [...] }` vs `[...]` — consistent?\n\n---\n\n### 3. Security Review\n\n- Authentication requirements stated for every endpoint?\n- Authorization: can users access other users' resources? Is it enforced?\n- Rate limiting: mutation endpoints (`POST`, `PUT`, `DELETE`) protected?\n- Input validation constraints defined in spec (max lengths, allowed values)?\n- Sensitive data in responses? (passwords, tokens, internal IDs, PII)\n- Webhook endpoints: HMAC signature verification mentioned?\n\n---\n\n### 4. Breaking Change Analysis\n\nIf reviewing a v2 or modification to an existing API:\n\n| Change | Breaking? |\n|--------|-----------|\n| Add new optional field to response | No |\n| Add new required field to request | **Yes** |\n| Remove field from response | **Yes** |\n| Rename field | **Yes** |\n| Change field type | **Yes** |\n| Change status code | **Yes** |\n| Add new endpoint | No |\n| Remove endpoint | **Yes** |\n\nList every breaking change with a migration guide.\n\n---\n\n### 5. Developer Experience\n\n- Field names self-documenting? (`userId` not `uid`)\n- Error messages actionable? (\"Email is required\" not \"invalid input\")\n- Pagination cursor-based or offset-based? (cursor preferred for large/live datasets)\n- Batch endpoints for operations typically done in loops?\n- Consistent use of `_at` suffix for timestamps (`created_at`, `updated_at`)?\n\n---\n\n## Output Format\n\n```\n## API Review: [API Name]\n\n### Summary\n[2-3 sentence quality assessment]\n\n### Findings\n\n[SEVERITY] Category — METHOD /path\nIssue description.\nSuggested fix: ...\n\n### Breaking Changes\n[List or \"None identified\"]\n\n### Recommendations\n[Prioritized improvements]\n\n### Score: [X/10]\n```\n\n**Severity levels:**\n- `CRITICAL` — Security hole or data loss risk\n- `HIGH` — Bug that will cause real failures\n- `MEDIUM` — Consistency or DX issue\n- `LOW` — Style or minor improvement\n\n---\n\n## Rules\n\n- Flag **every** mutation endpoint that doesn't explicitly state its auth requirement\n- Unbounded list endpoints (no pagination, no LIMIT) are always rated **MEDIUM** or higher\n- REST violations rated **LOW** unless they cause real interoperability problems\n- Never approve an API that exposes user data from other users without authorization checks\n- If the API has no versioning strategy: flag it as **MEDIUM** and suggest `/v1/` prefix\n\n## Playground\n\n
API Contract ReviewerExample · SkillSlap
Input: OpenAPI excerpt
POST /api/skills\nrequestBody:\n  content:\n    application/json:\n      schema:\n        type: object\n        properties:\n          title: {type: string}\n          content: {type: string}
Output: Contract review
🔴 No required fields declared\nBoth title and content must be\nrequired. Add:\n  required: [title, content]\n\n🔴 No maxLength on content\nUnbounded string → DoS via huge\npayloads. Add maxLength: 50000\n\n🟡 Missing 401 / 422 responses\nDocument error cases so clients\nknow what to expect on bad input.\n\n🟡 No description on properties\nAdd description: fields for SDK\nand docs auto-generation.
"}}