Content
85%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 a high-quality, domain-specific guide: actionable rewrites, a well-sequenced workflow with validation, and lean expert knowledge. Its main weakness is progressive disclosure — it points readers to references/ files that are not present in the bundle.
Suggestions
Add the missing references/investigation-playbook.md and references/learnings.md files referenced in the body (Step 2 and the Learnings log section), or remove/inline the links so no navigation path dead-ends.
Tighten the repeated single-team-vs-multi-team raw-SQL argument in Step 0 into a single statement to cut length without losing the rule.
Consider moving the dense Background file-path listing into a references file so the SKILL.md overview stays scannable, with the existing links pointing at real files.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Dense with PostHog-specific knowledge Claude lacks (exact file paths, line numbers, named rewrites, printer internals) with no padding about what ClickHouse/HogQL are; but at ~170 lines some prose recurs (e.g. the single-team-vs-multi-team raw-SQL argument is restated across Step 0) and could be tightened. | 4 / 5 |
Actionability | Provides copy-paste-ready rewrites ('SELECT argMax(properties, version) FROM person WHERE ... GROUP BY id', 'sumIf(amount, event=\'purchase\')', 'replace every JSONExtract*(properties, \'X\') with properties.X'), exact EXPLAIN invocations, and specific migration/printer entry points with line numbers covering the common cases. | 5 / 5 |
Workflow Clarity | A clear Step 0 → Step 5 sequence fronted by a triage table, with explicit validation checkpoints: assert index use via 'get_index_from_explain', 'Measure before suggesting' with before/after query_duration_ms/read_bytes, and test discipline that says to 'flip the change off to confirm the test exercises your path'. | 5 / 5 |
Progressive Disclosure | Structure and reference signaling are good (explicit markdown links, one-level-deep pointers to references/investigation-playbook.md and references/learnings.md), but those referenced files do not exist — the references/ directory is absent — so navigation leads to dead ends rather than a properly split bundle. | 3 / 5 |
Total | 17 / 20 Passed |