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.
A well-structured, actionable skill body that uses progressive disclosure effectively and sequences its workflows with strong validation checkpoints and feedback loops. The main room for improvement is mild verbosity in the semantic-layer workflow and relying on reference files for complete query examples.
Suggestions
Tighten the semantic-layer workflow prose (e.g., the MarkdownDefinition trust paragraph) to its load-bearing rules so the section reads closer to anchor 5 for conciseness.
Inline one short end-to-end analytics example query in the 'Querying analytics data' section so a reader can execute without first opening a reference file, raising actionability toward 5.
Consider a one-line 'start here' pointer at the top naming the three workflows, so first-time readers land on the right branch faster.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Largely lean and assumes Claude's competence ('execute-sql is for discovery, the read tool is for retrieval'), with reference link lists kept as compact indexes; the semantic-layer section is long but load-bearing nuance rather than padding, leaving only minor tightening opportunities. Not a 5 because the business-number workflow could be trimmed slightly without losing essential guidance. | 4 / 5 |
Actionability | Provides concrete, executable guidance — a real SQL example querying system.information_schema.metrics, named tools (posthog:execute-sql, posthog:data-catalog-metric-run), and specific column references (certification on system.information_schema.tables); minor gaps remain because full example queries are deferred to reference files rather than shown inline. | 4 / 5 |
Workflow Clarity | Three clearly numbered workflows with explicit sequencing and validation checkpoints — 'Do this before the first query-* call', 'An empty result means no governed definition exists', 'An unknown-table error means this project has no data catalog' — plus a guarded destructive/batch step (metric creation only after user confirmation, never for one-offs) with clear feedback loops. | 5 / 5 |
Progressive Disclosure | SKILL.md functions as a clear overview pointing to ~45 one-level-deep reference files organized by domain (Data Schema, HogQL References, Analytics Query Examples), each signaled as a markdown link; references verified to exist as real bundle files, with no deep nesting and easy navigation. | 5 / 5 |
Total | 18 / 20 Passed |