Content
80%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.
An exceptionally lean and actionable overview that assumes Claude's competence and routes detail to references correctly. Its weaknesses are the absence of an explicit install/verify workflow for a repo-wide batch operation, and bundle-level gaps where the most-cited reference files do not exist alongside SKILL.md.
Suggestions
Add an explicit numbered install workflow to the Git hooks section (owner consent → run scripts/install-git-hooks → verify with scripts/install-git-hooks --check) so the repo-wide arming operation has a validation checkpoint.
Ship CHECKS.md and kendex.settings.toml.example in the skill bundle, or inline a minimal check-contract summary, since the body defers to CHECKS.md as the owner of check contracts but the file is absent.
Surface the pre-push judgment sequence (read refs/index → verify tip is HEAD → run enabled byte-ceiling checks) as an ordered list rather than prose conditions, mirroring the reference file's clearer commit-chain listing.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, pointer-only prose with zero explanation of concepts Claude already knows — it never explains what git hooks are, and lines like "Exit codes are `0` clean, `1` violations and `2` usage, configuration or collection error" add only skill-specific information. Every sentence directs a read or an action, matching the 'every token earns its place' anchor. | 5 / 5 |
Actionability | The opening bash block gives four copy-paste-ready invocations with scope flags, and the rest supplies concrete decision rules ("Refuse a push whose tip is not HEAD, whose index differs from HEAD"), a hard Git 2.45.1 version floor, and exact file/script paths that all exist in the bundle. This is fully executable guidance covering the common cases. | 5 / 5 |
Workflow Clarity | Sequencing exists only implicitly via "Before installing... read X" / "Before changing setup... read Y" conditionals; there is no explicit install sequence and no post-install verification step even though arming hooks is a repo-wide batch operation (the `--check` verifier is only in frontmatter, never surfaced as a workflow step). The batch-operation cap of 3 applies. | 3 / 5 |
Progressive Disclosure | Structure is genuinely one level deep with well-signaled, anchor-linked references and real bundle files (references/hooks-and-settings.md and all named scripts exist), but CHECKS.md — declared "the owner of check contracts" and cited three times — and kendex.settings.toml.example are missing from the bundle, breaking navigation to the skill's most important reference. That is more than the 'minor organization gaps' of anchor 4. | 3 / 5 |
Total | 16 / 20 Passed |