CtrlK
BlogDocsLog inGet started
Tessl Logo

mcclowes/api-design

Use when designing, reviewing, or implementing HTTP APIs — error and warning handling, resource state and lifecycle, read-endpoint structure, pagination, and authentication. Triggers on error responses and formats, response envelopes, webhook payloads, how an endpoint should fail; modelling a resource lifecycle (status fields, state machines, webhook event names, enum vs parseable string); structuring read endpoints (screen-shaped/BFF vs canonical resource, aggregation, cursor vs offset pagination); and auth design (security schemes, API keys vs bearer tokens, stepped-up tokens). Apply whenever an API surfaces a failure, state change, view of data, or auth requirement to a client.

96

1.70x
Quality

90%

Does it follow best practices?

Impact

99%

1.70x

Average score across 8 eval scenarios

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

criteria.jsonevals/scenario-3/

{
  "context": "The user asks for the JSON error response body for a payouts endpoint with three distinct failure modes (expired bank token, daily limit exceeded, third-party vendor rejection). The criteria check whether the design follows the skill's error-handling conventions — a unified issues array, namespaced string codes with no separate type field, correlation metadata, and a dedicated structure for third-party errors — without those conventions being stated in the task.",
  "type": "weighted_checklist",
  "checklist": [
    {
      "name": "Unified issues array",
      "description": "The response uses a single `issues` array with one entry per failure, not separate `errors`/`warnings` arrays or a single top-level error object",
      "max_score": 8
    },
    {
      "name": "Namespaced dot-string issue codes",
      "description": "Each issue carries a single namespaced code in `{domain}.{class}.{reason}` form (e.g. `payout.unauthorized.token_expired`), not numeric or flat strings",
      "max_score": 8
    },
    {
      "name": "No separate type field",
      "description": "Issue objects do NOT include a separate `type` field alongside the namespaced `code` — the class is parsed from the code itself",
      "max_score": 8
    },
    {
      "name": "Severity present",
      "description": "Each issue includes a `severity` field (e.g. error/warning)",
      "max_score": 6
    },
    {
      "name": "correlationId present",
      "description": "The response includes a `correlationId` for debugging",
      "max_score": 6
    },
    {
      "name": "Timestamp present",
      "description": "The response includes a `dateTime`/timestamp field",
      "max_score": 4
    },
    {
      "name": "Third-party error surfaced via object",
      "description": "The Sequra (vendor) rejection is surfaced via a dedicated `thirdParty` object that carries the vendor's own code, rather than being flattened into the top-level issue code",
      "max_score": 8
    },
    {
      "name": "Descriptive string codes not numeric",
      "description": "Codes are descriptive strings, not opaque numeric codes",
      "max_score": 6
    },
    {
      "name": "Message and links where useful",
      "description": "Issues include a human-readable `message` and/or `links` for at least some failures",
      "max_score": 4
    }
  ]
}

README.md

SKILL.md

tile.json