Content
78%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 well-structured, domain-specific guide that assumes Claude's competence and supplies product knowledge Claude lacks (attribution rules, view semantics, naming honesty) alongside an executable four-step workflow with a test-before-save checkpoint. It loses a little on conciseness and actionability because some prose could be trimmed and the canonical SQL recipes live in the referenced file rather than inline.
Suggestions
Trim the two-substrates intro and the 'Everything else is just table data' elaboration; the mapping table and Step 2 already convey the raw-tables-vs-views split.
Inline the one or two most-used base subqueries (e.g. the PR throughput and team semi-join recipes) from hogql-recipes.md so the common path is copy-paste ready without a file hop.
Add an explicit validate→fix→revalidate loop around the execute-sql test in Step 2 (e.g. 'if the query errors, fix the JSON-unwrapping/timestamp parsing and re-run before saving').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with product-specific knowledge Claude does not already know (CI↔PR attribution by PR number, Nullable-JSON unwrapping, bot-detection list, honest naming of open_to_merge_seconds) and never pads with basics like 'what a PR is'. It is efficient but a few prose passages (the two-substrates intro, the 'Everything else is just table data' elaboration, and the large mapping table) could be trimmed without losing actionable content. Not 5 because of these minor instances of over-explanation; not 3 because it is well above 'mostly efficient with some unnecessary explanation'. | 4 / 5 |
Actionability | Gives concrete, executable guidance: exact table/view names, named MCP tools (engineering-analytics-sources, execute-sql, insight-create, subscriptions-create), specific HogQL functions (parseDateTimeBestEffort, ifNull, JSONExtractArrayRaw, splitByChar), a literal bot-detection predicate, and a copy-paste insight-create JSON payload. Not 5 because the actual base SQL subqueries are deferred to references/hogql-recipes.md rather than shown inline, so the most copy-paste-ready SQL is one hop away; not 3 because what is inline is genuinely executable, not pseudocode. | 4 / 5 |
Workflow Clarity | A clear four-step sequence — Step 1 discover tables, Step 2 write HogQL, Step 3 save as insight, Step 4 subscribe — with an explicit validation checkpoint ('Test the query with the execute-sql MCP tool ... before saving anything') and a multi-source clarification gate ('With multiple sources, ask which repo the user means'). Not 5 because there is no explicit fix-and-revalidate feedback loop and the subscribe step delegates detail to another skill, leaving minor validation gaps; not 3 because the sequence and a real checkpoint are present. The destructive/batch cap does not apply: the workflow creates insights/subscriptions rather than destroying or batch-overwriting data. | 4 / 5 |
Progressive Disclosure | SKILL.md is an overview with clearly signaled, one-level-deep references: 'Copy the base subqueries from references/hogql-recipes.md' (verified real file), and appropriate cross-skill pointers (managing-subscriptions, creating-ai-subscription) rather than inlining their content. Content is well split — overview, table mapping, four steps, 'What NOT to rebuild', and 'Caveats' — with the bulk SQL deferred to the reference. Not 4 because navigation is clear and references are exactly one level deep with no nested pointers. | 5 / 5 |
Total | 17 / 20 Passed |