Content
71%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.
This is a dense, highly actionable release runbook with exceptional validation coverage and error-recovery loops, no filler, and clearly signaled external references. Its weaknesses are structural: step 3 is an unmanageable run-on paragraph, and policy sections (catalog compatibility, main channel, secrets) are inlined where reference files would keep SKILL.md an overview.
Suggestions
Break step 3 into numbered sub-steps or a checklist (commit with COLLATE=1, verify PR merged, ancestry check, changelog-entries --release check, dispatch, watch, verify tag, retry policy) so the sub-sequence is extractable at a glance.
Move the Catalog compatibility, Main channel, and Secrets sections into one-level-deep reference files (e.g. references/catalog.md, references/secrets.md) with brief pointers from SKILL.md.
Give full invocation forms for tools named without arguments (tools/release-previous-tag, tools/release-installer-check, tools/catalog-release-check) and link or define 'the orch job runner'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with repo-specific facts, explains no concepts Claude already knows, and carries no padding — nearly every token earns its place. It falls short of anchor 5 because some conditions are restated across sections (tag-move rules in step 4 vs. the workflow section, retry guidance repeated) and the density itself forces re-reading where a trimmer layout would not. | 4 / 5 |
Actionability | Mostly executable: exact commands with flags ("gh workflow run release.yml --repo vanillagreencom/kendex --ref main -f tag=\"v<version>\" -f release_commit=\"<mergeCommit.oid>\"", "git merge-base --is-ancestor", "git ls-remote --tags origin v<major>") and explicit success criteria. Minor gaps keep it below anchor 5: several tools are invoked by name only ("tools/release-previous-tag", "tools/release-installer-check", "tools/catalog-release-check") without argument forms, and "the orch job runner" is unreferenced. | 4 / 5 |
Workflow Clarity | The numbered sequence 1-5 has abundant explicit validation checkpoints and error-recovery loops ("A nonzero exit halts the release", "Stop on a failed read, ancestry check or changelog check", re-collate-and-repeat instructions, retry rules, major-tag SHA verification), matching anchor 4-to-5 territory for a release workflow with destructive tag operations. It stays at 4 because step 3 buries roughly eight sub-operations (commit, PR merge verification, ancestry check, changelog check, dispatch, watch, tag verification, retry policy) in one run-on paragraph, muddling the sub-step order. | 4 / 5 |
Progressive Disclosure | The body has clear section headers and well-signaled one-level-deep links to repo docs ("[release-version rule](../../../skills/commit-guards/CHECKS.md#release-versions)", "[release standard](../../../changelog.d/README.md#release-standard)", "[npm-deploy](../npm-deploy/SKILL.md)"), and no bundle files exist to point to. But substantial policy material that would sit better in reference files — the full workflow asset inventory, Catalog compatibility, Main channel, and Secrets sections — is inlined wholesale, leaving SKILL.md as the complete detail rather than an overview, which matches 'could be better organized' rather than anchor 4's 'most content is appropriately placed'. | 3 / 5 |
Total | 15 / 20 Passed |