Content
88%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.
An exceptionally dense, high-signal code-map skill: it teaches non-obvious invariants (edge-triggered ordering, emergent session close, field authority, the bare-devMac binding bug) with concrete paths and directives throughout. The weaknesses are minor: some gotcha paragraphs over-run with nested parentheticals, and the Gotchas section has a duplicate item number (two 7s) that breaks the list's navigability.
Suggestions
Fix the Gotchas numbering: two items are numbered 7 (LatestEventsPerMAC and the MAC-keyed/devGUID one), leaving the list running 1-7, 8, 7, 9 — renumber to a clean 1-10 so individual gotchas can be cited unambiguously.
Tighten Gotcha 1 and Gotcha 8: Gotcha 1 restates the OR-composition sites twice, and Gotcha 8's qualified-but-colliding-argument parenthetical is trimmable depth; halving each would preserve every invariant while improving readability.
Consider moving the deepest gotchas (1 and 8) into a references/ file with one-line summaries in SKILL.md, keeping the main file to the call order, view relationships, and field-authority core.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every sentence carries project-specific, non-derivable knowledge (no SQL or general-concept padding — e.g. "insert_events() runs before presence updates... the edge-triggered design would break — firing never, or every cycle"), so content density is high. Not 5 because Gotchas 1, 6, and 8 contain repetitive restatement and deeply nested parentheticals that could be trimmed (Gotcha 1 enumerates the OR-composition sites twice; Gotcha 8's qualified-but-colliding-argument parenthetical is optional depth); not 3 because the verbosity is construction, not explanation of things Claude already knows. | 4 / 5 |
Actionability | For a reference/instruction skill the guidance is fully concrete and executable: exact file paths and function names, a 14-step call order with per-step rationale, and explicit directives like "To close a session, insert the right Events row — never mutate Sessions directly" and "Check any new query here with EXPLAIN QUERY PLAN at a realistic row count". Not 4 because specific guidance covers the common modification cases with no key details missing. | 5 / 5 |
Workflow Clarity | The process_scan() call order is a clearly sequenced 14-step pipeline in which every step's load-bearing position is explained ("If this ran after the presence update, every query would see the new value..."), with verification guidance baked in (EXPLAIN QUERY PLAN, the two-sibling-test insight, the CI schema drift guard). Not 4 because checkpoints and error-recovery reasoning are explicit, not implied; there is no destructive/batch operation lacking a validation loop. | 5 / 5 |
Progressive Disclosure | Well-organized single-file structure with clear sections (Scope, tables, views, call order, field authority, Gotchas, cross-doc routing) and clearly signaled one-level-deep cross-skill references ("see `database-patterns`", "see `plugin-development`"). Not 5 because the Gotchas list is mis-numbered — two items are labeled 7, with the sequence running 1–7, 8, 7, 9 — and the deepest gotchas (1, 8) are long monolithic paragraphs that could live in a references file; not 3 because navigation is otherwise easy and all cross-references are explicit. | 4 / 5 |
Total | 18 / 20 Passed |