Design or review an HTTP/REST/GraphQL API for versioning, pagination, error shapes, idempotency, auth, status codes, cache headers, and breaking-change management.
SkillScore82Maintained
Automatic
◆Coding pack
Last verified 10/10/2026
What it changes
Passed 18 of 22 test cases with the skill, and 16 of 22 without it.
Without skill73%
With skill82%
Checks it passed that the model alone missed
Includes a requestId field in the error payload.
Enforces a hard maximum limit cap on requested page size.
2 fixed16 passed either way4 still failing0 broke
Pass-rate lift
+9 pp
Tokens
+68%
Agent turns
0%
Response time
-5%
Model gemini-3.6-flashMeasured 10/10/2026v218 of 22 cases passed with skill
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 2 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 2
Prompt
Our social networking service has an endpoint to fetch a user's follower list (GET /users/usr_44/followers). The team is debating using offset-based pagination (?page=3&pageSize=50) or cursor-based pagination (?cursor=eyJpZCI6MTIzfQ&limit=50). The followers table receives thousands of new writes per second. Which pagination strategy should be established as the default?
What was checked, without and with the skill
Checked
Without skill
With skill
Uses cursor-based pagination for high-volume listing endpoints.
Passed
Passed
Enforces a hard maximum limit cap on requested page size.
Missed
Passed
case-10 · gemini-3.6-flash · 10/10/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md187 linessingle file
Invocation points:
Adding a new public API endpoint
Redesigning an internal API boundary between services
Code review of a PR that introduces HTTP handlers
A slice whose acceptance criteria include "the API works"
A GraphQL schema change
<core_principle>
CALLERS OUTLIVE YOUR ASSUMPTIONS. An API you ship today has to keep working when your internals change, when the mobile app version two is still in use, and when a third party integrates against it. Design for extension, not just for the current caller.
HONEST STATUS CODES. 200 OK with {"error": "not found"} is a lie. 404 says not found. Use the HTTP semantics the protocol offers — HTTP clients, caches, and intermediaries rely on them.
PAGINATION IS NON-OPTIONAL. Any list endpoint that doesn't paginate will eventually get a request for "all records" that kills your database.
</core_principle>
Step 1: Gather the contract
Answer, or ask (one round, 1–3 questions):
Who are the callers? Internal service / mobile app / public third-party / same-repo frontend.
Design, change, or review an HTTP/JSON API surface — endpoints, request/response shapes, authentication and authorization, pagination, idempotency, rate limits, versioning, and deprecations. Use when adding or modifying an HTTP endpoint, reviewing an OpenAPI spec or HTTP route diff, or deciding whether an HTTP API change breaks consumers. Do not use as a protocol-compatibility checklist for gRPC/protobuf, GraphQL, WebSockets, or other non-HTTP/JSON interfaces.