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-8/

{
  "context": "The user proposes `kyb.review` as a status that is both a leaf value and a parent of `kyb.review.approved`/`kyb.review.rejected`, for a dashboard whose job is to show who owns the next move. The criteria check whether the answer flags the parent-as-both-leaf-and-container problem and chooses the segment axis to match the dashboard's actual job.",
  "type": "weighted_checklist",
  "checklist": [
    {
      "name": "Flags bare parent used as leaf and container",
      "description": "Flags that `kyb.review` used as BOTH a leaf status AND a container with children (approved/rejected) breaks prefix matching",
      "max_score": 8
    },
    {
      "name": "Parent must be pure container or flat leaf",
      "description": "States the rule: a parent segment must be a pure container (every state carries a leaf) OR a flat state with no children — never both",
      "max_score": 8
    },
    {
      "name": "Worst when children terminal",
      "description": "Notes this is worst when the children are terminal outcomes",
      "max_score": 4
    },
    {
      "name": "Middle segment is a chosen axis",
      "description": "Explains that the middle segment is an axis you choose deliberately, not an incidental grouping",
      "max_score": 6
    },
    {
      "name": "Group by actor for the dashboard's job",
      "description": "Recommends grouping by actor (e.g. awaiting_user vs in_review/awaiting_us) because the dashboard's job is 'who owns the next move'",
      "max_score": 8
    },
    {
      "name": "Enables one-segment prefix match",
      "description": "Notes the actor-axis grouping makes the dashboard query a one-segment prefix match",
      "max_score": 6
    },
    {
      "name": "States name present conditions",
      "description": "Resulting states are named for present conditions",
      "max_score": 4
    }
  ]
}

README.md

SKILL.md

tile.json