Content
75%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 index-style skill: lean overview, clear priority taxonomy, and an appropriate one-level-deep reference bundle with a workable prefix-based navigation scheme. The main issues are the dangling external document references in the review-protocol paragraph, pointing readers at the internal template file `_sections.md`, and the absence of any explicit validation guidance (e.g., EXPLAIN-based verification) in the body.
Suggestions
Remove or gate the repo-specific review-protocol paragraph (AGENTS.md, codex-review-protocol.md, pull-request-workflow.md) — those files are not in the skill bundle, so the instructions are unactionable for most users of the skill.
Replace the hand-picked three-file list in How to Use with the prefix convention itself (e.g., "all rules live in references/ as <prefix>-<topic>.md; see the table for prefixes") and drop `_sections.md`, which is an internal file containing demonstrative template text.
Add one line telling the reader to verify optimizations with EXPLAIN ANALYZE before/after applying a rule (pointing to monitor-explain-analyze.md), which would also strengthen workflow validation for a database-operations skill.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is short and lean — a priority table, a when-to-apply list, and a brief file-structure description — with no re-explanation of concepts Claude already knows. It loses a point for redundancy (the When-to-Apply bullets largely duplicate the description's triggers) and the repo-specific review-protocol paragraph that is irrelevant to most invocations. | 4 / 5 |
Actionability | The prefix table ("query-", "conn-", "security-"...) plus the description of each rule file's contents ("Incorrect SQL example with explanation", "Optional EXPLAIN output or metrics") gives concrete, deterministic navigation to executable guidance. It stops short of 5 because no command or worked example appears in the body itself, and the review-mode paragraph directs the reader to follow files ("AGENTS.md", "docs/codex-review-protocol.md") that are not present in the bundle. | 4 / 5 |
Workflow Clarity | Usage is well sequenced: explicit applicability conditions, an impact-ordered priority table, then instructions for reading rule files that contain incorrect-vs-correct examples and metrics. Validation checkpoints are only implicit (e.g., monitor-explain-analyze exists as a rule file but the body never says to verify optimizations via EXPLAIN), keeping it below anchor 5. | 4 / 5 |
Progressive Disclosure | The structure matches the bundle reality: a concise overview, one-level-deep references/ files organized by filename prefix, and all three files named in How to Use (query-missing-indexes.md, query-partial-indexes.md, _sections.md) verified to exist. Minor gaps: only 3 of 34 rule files are named (discovery depends on the prefix convention), the internal `_sections.md` (which still contains demonstrative template text) is listed as a reading target, and the body points to non-bundle paths like `../../../docs/agents/pull-request-workflow.md`. | 4 / 5 |
Total | 16 / 20 Passed |