Content
80%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.
A well-structured, highly actionable skill body: executable code covers the common cases, and progressive disclosure via four real one-level-deep references is exemplary. The main gaps are modest redundancy between the summary list and detail sections (plus ORM explanations Claude already knows) and a write-mode workflow that lacks explicit sequencing and validate/retry checkpoints despite covering database and batch operations.
Suggestions
Trim the 'Why NOT ORMs' rationale (Claude knows N+1 and hook pitfalls) to a one-line policy statement, and cut items in the 15-point summary that are fully re-covered by later sections.
Give Write mode an explicit numbered sequence (scan conventions → draft query with parameters → wrap transactions → add error/NULL handling → verify with the testing reference) so 'follow the skill's sequential instructions' has a concrete referent.
Add an explicit validation/feedback checkpoint for batch and transactional operations (e.g., verify affected row counts, retry the whole transaction on serialization failure 40001) in the main body, not only in the error-patterns table.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and mostly lean with executable examples, but the 15-item "Best Practices Summary" restates points re-covered by later sections, and "Why NOT ORMs" explains concepts (N+1 problems, magic hooks) Claude already knows. This sits between the mostly-efficient (3) and lean (5) anchors — efficient with minor over-explanation. | 4 / 5 |
Actionability | Guidance is copy-paste-ready and covers common cases: parameterized GetContext calls, sqlx.In with Rebind, an allowlist for dynamic sort columns, errors.Is(err, sql.ErrNoRows) handling with two complete function variants, defer rows.Close() plus rows.Err() checking, and concrete pool tuning values. It fully matches the executable anchor. | 5 / 5 |
Workflow Clarity | The Modes section sketches a rough sequence (background agent to grep conventions before generating; sub-agent scan during review) but "follow the skill's sequential instructions" points at no numbered step list, and — for a skill whose scope explicitly includes database and batch operations — there is no validate→fix→retry feedback loop in the main workflow (only a 40001-retry row in the error table). Per the rubric's cap for database/batch operations, workflow clarity cannot exceed 3; it is not 2 because a rough sequence with error-checking patterns is present. | 3 / 5 |
Progressive Disclosure | The body is a well-organized overview with a Deep Dives section listing four real, one-level-deep reference files (transactions, testing, performance, scanning), each with a scope description, and detail is correctly deferred to them (e.g., the Transactions section is a pointer). Verified the referenced files exist and contain no further .md nesting. This matches the clear-overview anchor. | 5 / 5 |
Total | 17 / 20 Passed |