Content
61%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.
The body is an efficient, well-structured index for a large rule bundle: a clear priority table with filename prefixes, explicit applicability conditions, and verified one-level-deep references. Its weaknesses are navigational rather than structural — no explicit rule-selection workflow, only three example paths out of 35 rule files, and no validation checkpoint guidance for applying the SQL rules.
Suggestions
Add a short rule-selection step, e.g. "identify the task's category from the prefix table, then open references/<prefix>-<topic>.md" with one worked example (slow query → query-missing-indexes.md).
List the full set of rule files (or per-category file listings) instead of only three example paths, so Claude can navigate without guessing filenames.
Include a brief verification checkpoint for applied changes, e.g. confirming improvements with EXPLAIN ANALYZE or pg_stat_statements (monitor- prefixed rules), which the current workflow omits.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean: a priority table, six short trigger bullets, and a brief description of the rule-file format, with no padding or explanations of concepts Claude already knows. It misses anchor 5 only because the opening paragraph and "When to Apply" bullets restate the frontmatter abstract/description, a small redundancy that could be trimmed. | 4 / 5 |
Actionability | Guidance is structural rather than executable: "Read individual rule files for detailed explanations and SQL examples" plus a prefix naming convention and three example paths. The convention lets Claude infer file names, but the body never says how to map a task to a specific rule file, and only 3 of the 35 reference files are shown — matching anchor 3's 'some concrete guidance but incomplete' rather than anchor 4's mostly-executable direction. | 3 / 5 |
Workflow Clarity | There is no sequenced procedure: the implied flow is "check When to Apply → find the relevant rule file → apply it", but which rule file to open for a given problem (e.g. a slow query vs. pool exhaustion) is left implicit, and no validation or verification steps are described. Per the simple-skill exception this could score higher, but the single action — selecting the right reference — is ambiguous, capping it at anchor 3. | 3 / 5 |
Progressive Disclosure | SKILL.md is a genuine overview: a category/priority/prefix table, a description of each rule file's contents, and one-level-deep references (references/query-missing-indexes.md, references/schema-partial-indexes.md, references/_sections.md — all verified to exist) alongside 35 flat rule files. It falls short of anchor 5 because only three arbitrary example paths are listed rather than a complete or per-category index, and meta files (_contributing.md, _template.md) are present in the bundle but unexplained. | 4 / 5 |
Total | 14 / 20 Passed |