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.
The body is an unusually executable instruction set: complete configs, a safe idempotent jq merge, exact validation commands with expected outputs, and proactive handling of subtle failure modes (bootstrap ordering, base-branch verifier, GNU/BSD decode portability). Its main weaknesses are a handful of over-long rationale passages that could be tightened, and progressive disclosure — the skill's central reference file and example assets are cited as mandatory but are absent from the bundle, forcing detail to be inlined in SKILL.md instead.
Suggestions
Ship the referenced bundle files: `references/ai-governance.md` is declared mandatory reading ("Read ... before responding") and `examples/ai-governance/evaluate.sh` and `ai-governance-check.yml` are named copy sources, yet no references/ or examples/ directory exists in the skill — include them or inline the minimal content actually needed.
Move mode-specific detail (the check/audit/explain sections, the per-pack protected_paths variants, and the jq settings-merge program) into `references/ai-governance.md`, keeping SKILL.md as the wizard plus a generate-mode overview.
Trim long rationale passages to a single sentence each — e.g., the postToolUse no-op explanation and the audit mode's closing "fleet-visibility value... (Phase 4)" paragraph.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and operational — no space is spent on concepts Claude already knows, and long passages carry non-obvious project rationale (why postToolUse never re-evaluates, why yq must not be self-installed, why the workflow fetches the base branch's copy). A few passages could still be trimmed — e.g., the ~70-word postToolUse no-op explanation and the audit mode's closing "fleet-visibility value... (Phase 4)" positioning paragraph — which keeps it at anchor 4 rather than the lean anchor 5. | 4 / 5 |
Actionability | Guidance is copy-paste executable throughout: the full `.ai-governance.yaml` policy shape with per-pack deltas, complete `.github/hooks/*.json` configs, a working `jq` merge program with idempotency check, the raw-file `gh api` audit loop, and a Validation block showing exact commands with expected outputs and exit codes ("exit 2" for deny). This matches anchor 5's fully-executable, common-cases-covered standard. | 5 / 5 |
Workflow Clarity | Generate is a 9-step numbered sequence with an explicit Validation block giving expected per-tier outputs, a yq presence check with stop-and-ask fallback, idempotent re-runs ("skipping the append if this exact command is already registered"), and a proactive two-stage bootstrap ordering that prescribes the fix for the known first-PR failure mode — explicit validation plus error-recovery loops, i.e. anchor 5 rather than anchor 4's "minor validation gaps". | 5 / 5 |
Progressive Disclosure | References are clearly signaled ("Read `references/ai-governance.md` before responding", copy sources under `examples/ai-governance/`), but none of these files exist in the skill's bundle — no `references/`, `examples/`, `scripts/`, or `assets/` directory is present — so the mandatory pre-response read is a dangling pointer, and mode-level detail (check/audit/explain, the full jq program, policy pack variants) is inlined rather than split out. Clear signaling (an anchor-4/5 trait) combined with unverifiable references and inline-heavy placement sits at anchor 3. | 3 / 5 |
Total | 17 / 20 Passed |