CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

review-api-error-conventions

Use when reviewing changes to HTTP handlers under src/api/ to check that error responses go through apiError() with a status and code from the team's tables.

Quality

84%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

82%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured, highly actionable convention skill: complete decision tables, an explicit severity model, and illustrative good/bad examples. Its weaknesses are minor — a redundant intro paragraph, some typos in the status table, and lookup tables that could be split into a reference file.

Suggestions

Remove the opening paragraph that restates the description and the duplicated rule in "Findings to Raise" ("Not using apiError is a critical, MUST FIX error") to tighten conciseness.

Fix the typos in the HTTP Status Table ("invalidate structure" → "invalid structure", "resources does not exixt" → "resource does not exist", "they specific HTTP verb" → "the specific HTTP verb", "applicaiton" → "application"), since the table is the authoritative source reviewers copy from.

Consider moving the HTTP Status Table and Error Code Table into a references/ file (e.g. references/tables.md) so the main body holds only stance, rules, and examples.

DimensionReasoningScore

Conciseness

Every section carries project-specific rules rather than generic explanation, with copy-paste-ready examples. Minor trimming is possible — the intro paragraph restates the description, and the "Using the function" rule is repeated in "Findings to Raise" — so it is efficient but not fully lean.

4 / 5

Actionability

Complete lookup tables for HTTP statuses and error codes, an explicit severity taxonomy ("critical, MUST FIX" / major / minor), and concrete good/bad examples including the status-code-too-broad and status-error-mismatch cases. The guidance is executable as written for a review lens.

5 / 5

Workflow Clarity

The Stance section sequences the review (review all changed TS API code, only raise findings on violations, cite file/line and rule name) and "What not to flag" acts as an explicit guardrail, with severities mapped to concrete situations. Minor gaps remain (e.g. no ordering guidance when multiple rules are violated), and as a review lens rather than a build workflow it has no destructive-operation validation requirements.

4 / 5

Progressive Disclosure

A single well-organized SKILL.md with no bundle files; sections (Stance, Rules, Findings to Raise, What not to flag, tables, Examples) are clearly headed and easy to navigate. At ~130 lines the two lookup tables could arguably live in a reference file, which keeps it just below the ideal-placement anchor.

4 / 5

Total

17

/

20

Passed

Description

78%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, concrete description with an explicit trigger clause and tight scoping to the project's src/api/ error-handling convention. The only notable weakness is that the capability statement is embedded in the when-clause rather than stated separately, and a few natural trigger synonyms are absent.

DimensionReasoningScore

Specificity

"check that error responses go through apiError() with a status and code from the team's tables" names the function, the checked artifacts, and the scope ("HTTP handlers under src/api/") — several specific actions with minor gaps (finding severity/output not mentioned). Not 5 because it describes one composite check rather than multiple listed actions; clearly above the 1-2-action level 3.

4 / 5

Completeness

An explicit, concrete when-clause is present ("Use when reviewing changes to HTTP handlers under src/api/"), and the what (error responses must go through apiError with a table-listed status and code) is included. The what is folded into the when-clause rather than stated as its own sentence, so it falls short of the clearly-separated what-and-when anchor.

4 / 5

Trigger Term Quality

"reviewing changes", "HTTP handlers", "src/api/", "error responses", "apiError()" are natural phrases a user would say during a review. A few common variations are missing (e.g. "diff", "PR", "error handling conventions"), so it does not reach comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

The description is scoped to a specific project path, a specific function name, and team-specific tables — a clear niche with distinct triggers and minimal risk of firing for unrelated skills.

5 / 5

Total

17

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

crdant/review-lab

Path

review-lenses/review-api-error-conventions/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.