Content
77%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
An unusually high-signal conventions document: every rule names concrete files, helpers, and failure modes, and the contract-first workflow plus closing checklist give it genuine validation checkpoints. Its weakness is shape, not substance — at ~240 lines with no reference files, it front-loads everything (including RFC rationale and security analysis) into SKILL.md and repeats several points, where a leaner core with split-out references would serve progressive disclosure and token economy better.
Suggestions
Split the 'Deliberate non-adoptions' table, the 'Idempotency' section, and 'Cursors are opaque, not trusted' into reference files (e.g. references/non-adoptions.md, references/idempotency.md, references/cursor-security.md), leaving one-line verdicts with pointers in SKILL.md.
Deduplicate the cross-tenant 404-concealment explanation (Rule 2 vs. the checklist item) and the typed SQL bound-parameter rule (Rule 2's two long paragraphs) — state each once and reference it from the checklist.
Trim quoted RFC passages to the operative clause plus citation (e.g. keep '9457 §4 ... not to replace existing domain-specific formats' and drop the surrounding sentences) to cut the longest paragraphs to a few lines.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with genuinely non-obvious project knowledge and explains nothing Claude already knows, but it is still ~240 lines with padded passages: verbatim RFC quotes in the non-adoptions table, 150+ word discursive paragraphs (e.g., the 403-vs-404 authorization discussion), and points repeated across sections (404 concealment and the typed SQL bound-parameter rule each appear twice). Mostly efficient, but noticeably tighten-able — not the 4 anchor's 'minor instances'. | 3 / 5 |
Actionability | Guidance is fully concrete and executable: exact file paths for every mechanism, named helpers (`v2PaginationFields`, `booleanQueryFlagSchema`, `ForbiddenOperationError`), a copy-paste code snippet, model validation messages, and runnable verification commands (`bun run type-check`, `bun run check:audits`). Specific examples cover the common cases of adding or auditing a route. | 5 / 5 |
Workflow Clarity | Rule 5 lays out a clear ordered sequence (contract → use case → route → OpenAPI) where each layer is checked against the previous one, and the closing checklist is an explicit validation gate with commands and test files that fail until conformance is declared (list-pagination.test.ts, query-declaration.test.ts). The 'execute it somewhere before believing the suite' guidance adds an error-recovery checkpoint. | 5 / 5 |
Progressive Disclosure | Section headers, the 'Where the machinery lives' table, and one README link give real structure, but there are no bundle files at all: large self-contained sections (the RFC-by-RFC 'Deliberate non-adoptions' table, idempotency semantics, cursor security analysis) are inlined in SKILL.md where the rubric expects them split into one-level-deep reference files. This is the 'some structure, content that should be separate is inline' anchor — better organized than anchor 2's header-less wall, but clearly short of the well-signaled references at 4. | 3 / 5 |
Total | 16 / 20 Passed |