Content
82%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 strong reviewer checklist: dense with genuinely non-obvious, codebase-specific knowledge (exact file paths, line numbers, collation facts, CI job names) and fully actionable fixes demonstrated through a real worked PR. Its weaknesses are presentational — long parenthetical digressions that could be trimmed, and only one of the four checks formatted as a numbered review flow.
Suggestions
Convert the logging, dependency, and scanPresence checks into the same short numbered review-flow format used for the raw-SQL check, so a reviewer can follow one consistent step order across all four checks.
Trim the long parenthetical asides (the GraphQL rationale, the api_server_start.py rate-limiting precedent, and the MkDocs parser detail in the Scope section) to their one-line decision-relevant core — the facts are valuable but the sentences are two to three times longer than needed.
Consider moving the two worked-example sections (PR #1788 and the generalized broadcast-protocol example) into a references/ file with a one-line pointer per check, keeping SKILL.md to the check definitions and review flows.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly every sentence carries non-obvious codebase knowledge (e.g. 'devMac/eveMac/sesMac/scanMac/devParentMAC are declared COLLATE NOCASE at the column level', the five-plugin exception list, the devcontainer regeneration flow) rather than concepts Claude already knows, so it assumes competence. Not 5: several long parenthetical digressions — the GraphQL rationale, the 'per existing precedent: api_server_start.py's unauthorized-access-attempt alert fires unconditionally' aside, and the MkDocs parser explanation — could be tightened without losing information. Not 3: there is no padded explanation of known concepts; it is well above the midpoint. | 4 / 5 |
Actionability | Guidance is fully concrete: exact fixes ('Fix: DeviceInstance().getByMac(mac) is not None, delete the raw SQL'; 'add DeviceInstance.getAllByName(name) returning every match'), precise locations ('server/models/device_instance.py:102-105', 'server/plugin.py:769-791'), exact gating conditions ('fire only on "new" or "watched-changed", never on "watched-not-changed"'), and specific files to check ('.devcontainer/Dockerfile', 'Dockerfile.debian', 'install/ubuntu24/requirements.txt'). Per the code_vs_instruction note, this instruction-only skill's guidance is as actionable as copy-paste code. Not 4: there are no gaps — the worked PR #1788 example covers the common case end-to-end with both fix shapes. | 5 / 5 |
Workflow Clarity | The raw-SQL check has a clear 4-step numbered review flow with the key checkpoint ('Check the collation the query relies on... rather than assuming'), and each other check states what to verify, the failure mode, and the fix. Not 5: only one of the four checks is a numbered sequence — the logging, dependency, and scanPresence checks are well-specified prose but lack an equivalent stepwise review order, so a reviewer must assemble their own checklist order. Not 3: the sequences that exist are coherent with real checkpoints, above the midpoint. | 4 / 5 |
Progressive Disclosure | The body is well-organized into clearly headed sections (Scope, then one section per check, each with its worked example) and appropriately defers to existing resources by name ([[plugin-development]], [[plugin-readme]], test_plugin_conventions.py, docs/PLUGINS_IMPORT_BEHAVIOR.md) instead of duplicating them. Not 5: no bundle files exist and the ~60-line body keeps all four checks' detail inline where the two worked-example sections could plausibly live in reference files; it also slightly exceeds the under-50-line simple-skill threshold. Not 3: structure is good and references are clearly signaled, not buried. | 4 / 5 |
Total | 17 / 20 Passed |