Content
67%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 dense with domain-specific, non-obvious guidance and executable scripts, organized into well-labeled sections with a real, well-signaled reference file. Its main weaknesses are repetition — gitleaks and pin-by-SHA guidance each restated multiple times — and template placeholders that keep some examples from being copy-paste ready.
Suggestions
Consolidate the gitleaks guidance — currently spread across the checklist, 'CI pipeline structure', and 'Gitleaks in CI' — into one section, keeping only the core principle in SKILL.md and delegating both options' YAML to ci-examples.md.
State the 'pin, don't float' principle once and cross-reference it for the Actions-SHA case instead of re-explaining it in a second full bullet.
Trim trailing rationale clauses (e.g. "…is therefore easy to miss in a pure CI audit") to bare imperatives to reduce token cost without losing the instruction.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Largely efficient and free of beginner-concept padding, but gitleaks guidance is stated in three or more places (checklist, "CI pipeline structure", "Gitleaks in CI") and the Actions-SHA bullet explicitly re-explains the image-digest bullet's principle. Rationale sentences like "this is the same 'implicit assumption' mistake as the rest of this checklist… therefore easy to miss in a pure CI audit" could be trimmed. | 3 / 5 |
Actionability | Copy-paste-ready hook and graceful-degradation shell scripts with real commands (`pnpm verify`, `curl -sf --max-time 2`, `sonar-scanner`, `gitleaks git --pre-commit --staged -v`, baseline workflow). Minor gaps from template placeholders (`<external-check>`, `<external-scanner>`, `scripts/<external-check-name>.mjs`) that are not directly executable. | 4 / 5 |
Workflow Clarity | A checklist-driven audit sequence with explicit validation checkpoints (credential-then-reachability-then-check ordering, "show it failing once on a deliberate violation", querying real CI status after push). No single linear setup order ties the sections together — setup steps (write verify → hooks → activate → parity test → CI) must be inferred from section order. | 4 / 5 |
Progressive Disclosure | One clearly signaled, one-level-deep reference ([ci-examples.md](references/ci-examples.md), verified to exist) holding the Woodpecker/GitLab syntax, gitleaks YAML, ratchet implementation, and image reproduction. Minor gap: the two-option gitleaks comparison is summarized in the body and then repeated in the reference rather than fully delegated. | 4 / 5 |
Total | 15 / 20 Passed |