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 dense, high-value reference that documents genuinely non-obvious pipeline behavior (edge-triggered event design, emergent session closing, field-write authority) with named functions, files, and explicit do/don't rules. Its weaknesses are stylistic and structural rather than substantive: a few run-on gotcha paragraphs that could be tightened, described-but-unstructured validation loops, and a numbering error in the Gotchas list.
Suggestions
Fix the Gotchas numbering: item 7 appears twice (the LatestEventsPerMAC and MAC-keyed gotchas are both numbered 7) and the list then jumps to 9 — renumber sequentially.
Split Gotcha 8's ~300-word single paragraph into shorter sentences or a small cause/fix/test breakdown to preserve clarity without losing the detail; the same applies to parts of Gotcha 9.
Consider moving the deepest gotchas (e.g. 7-9 on view gating, SQL scoping, and IP-known logic) into a references/ file with one-level-deep pointers from SKILL.md, keeping the main body to the table map, call order, and authority mechanism.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly every sentence carries non-inferable, project-specific fact (call-order rationale, silent-failure modes, index coverage) with no padding of concepts Claude already knows. However, Gotcha 8 ("A correlated helper's `mac_column` argument silently binds to the helper's own inner row...") is a ~300-word single paragraph with nested parentheticals, and Gotcha 9 is similarly dense — trimmable verbosity, matching anchor 4 rather than 3 (nothing is padding) or 5 (a few passages sacrifice clarity for density). | 4 / 5 |
Actionability | Concrete, executable directives throughout: "To close a session, insert the right `Events` row — never mutate `Sessions` directly", "Check any new presence-adjacent query against both patterns", "Don't design around these tables ever becoming devGUID-keyed", each tied to named functions, files, and columns. Per the scoring note, absence of code in an instruction-only skill is not penalized when guidance is this actionable — and it fully is. | 5 / 5 |
Workflow Clarity | The 14-step "`process_scan()` call order — order is load-bearing" is a clearly sequenced list with per-step rationale ("If this ran after the presence update, every query would see the new value and the edge-triggered design would break") and explicit checkpoints ("Check any new query here with `EXPLAIN QUERY PLAN` at a realistic row count"). It falls short of anchor 5 because validate→fix→retry loops are described rather than structured, and the Gotchas section has a numbering defect (two items labeled 7, then a jump to 9) that slightly muddies an otherwise coherent sequence. | 4 / 5 |
Progressive Disclosure | Clear sections (Scope, Core tables, Key views, call order, Field-write authority, Gotchas) plus a dedicated "When to read this vs. other docs/skills" section with well-signaled one-level-deep pointers ("→ `database-patterns`", "see `plugin-development` and `docs/PLUGINS_DEV*.md`"). No bundle files exist, so nothing is misfiled, but the ~19KB body of deep-gotcha material is dense enough that some belongs in a reference file, and the duplicated gotcha numbering is a minor organization gap — anchor 4, not 5. | 4 / 5 |
Total | 17 / 20 Passed |