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.
A high-quality reference-style skill body: almost every line carries non-obvious operational rules, with concrete code, exact file paths, and real validation gates (live-cluster checks, check.sh exit 0, test_migrations.py coverage). The only notable weaknesses are placeholder-laden core template snippets and topic- rather than sequence-oriented organization that leaves the end-to-end workflow to be inferred.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with repo-specific facts Claude cannot know (node-role ownership rules, Kafka settings defaults, the run_mode gating table, the schema.py tuple table) and assumes competence — it never explains what ClickHouse or a migration is. A few passages could still be tightened, e.g. the very long CODEC bullet and the node-roles section repeating 'check where the object is read and written', which places it at anchor 4 ('efficient; minor instances of over-explanation that could be trimmed') rather than anchor 5. | 4 / 5 |
Actionability | Most guidance is executable: copy-paste-ready Kafka SETTINGS SQL, the run_mode gating snippet, exact engine signatures, the schema.py tuple table, and the HCL shell commands (`bash $HCL/gen-golden.sh && bash $HCL/gen-sql.sh`, `check.sh`). The anchor-4 fit comes from the core migration template containing placeholders (`SQL_FUNCTION()`, `node_roles=[...]`) and `hclexp locate` being invoked without any setup or usage pointer — minor gaps that keep it below fully copy-paste-ready anchor 5. | 4 / 5 |
Workflow Clarity | Sequences with explicit checkpoints are present despite the destructive/batch nature of migrations: a numbered pre-flight live-cluster check across dev/prod-us/prod-eu (including verifying new table names are unused), `check.sh # must exit 0` as a hard validation gate, and the two-step DROP COLUMN process with team coordination and a named CI failure mode (`DRIFT:` block) for feedback. It sits at anchor 4 rather than 5 because the sections are topic-organized rather than one end-to-end ordered workflow — the reader must assemble the order (check clusters → choose role → write migration → update schema.py → update HCL → check.sh → PR) themselves. | 4 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent), and the body appropriately defers the bulk of detail to one-level-deep, clearly signaled external files: AGENTS.md is pointed to up front ('comprehensive patterns, cluster setup, examples, and ingestion layer details') and again at the Kafka section ('has the sizing rules and the rest'), plus hcl/README.md, connection.py, and a runbook link — each with a stated reason to open it. The inline content is a genuine quick reference with clean section navigation and no nested references, matching anchor 5. | 5 / 5 |
Total | 17 / 20 Passed |