Content
77%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 well-structured, actionable skill body with strong progressive disclosure (all referenced bundle files exist and are clearly signaled) and a validation-backed workflow. The main weakness is token efficiency: a redundant Table of Contents and four sections restating the same no-drift rule could be consolidated.
Suggestions
Remove the Table of Contents and merge the overlapping Constraints, Philosophy, Anti-patterns, and Failure mode sections into one or two sections, keeping the no-silent-drift rule stated once.
Replace the hardcoded check-name list in the rg validation command with a pattern derived from the policy files, or move it to a reference, so the command does not go stale on renames.
Add one short example of a documented intentional mapping (e.g., a docs line mapping dependency-review to dependency-scan) so the mapping workflow step is copy-paste ready.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body includes a 12-line Table of Contents for a ~90-line document and restates the no-silent-drift rule across four sections ("Do not silently preserve mismatched names", "Treat check-name drift as a contract bug", "Accepting mismatches with no documented mapping rationale", "treat that as unresolved policy debt"). This is more than the minor trimmable instances of anchor 4 but stops short of anchor 2 because there is no over-explanation of concepts Claude already knows and every section is short. | 3 / 5 |
Actionability | Concrete, executable commands are provided ("bash .codex/skills/ci-check-name-parity/scripts/report_check_name_drift.sh", "npm test", a full rg invocation) plus concrete workflow steps. It misses anchor 5 because the rg validation hardcodes a brittle, time-sensitive list of check names and no example shows what a documented intentional mapping should look like. | 4 / 5 |
Workflow Clarity | The 5-step workflow has an explicit validation step ("Re-run repo validation after the rename or mapping change lands"), a fail-fast feedback loop ("stop at the first failed gate and fix it before continuing"), and error-recovery guidance in Failure mode ("If repo tests fail after a rename, do not claim the policy update is complete"), matching the anchor-5 pattern of validate -> fix -> re-validate rather than the minor-gaps profile of anchor 4. | 5 / 5 |
Progressive Disclosure | The References section signals each bundle file with a purpose ("Read when: you need the source map and naming rule") and every referenced file exists one level deep (references/comparison-matrix.md, references/contract.yaml, references/evals.yaml, scripts/report_check_name_drift.sh), with the body staying a genuine overview. This matches anchor 5's clear overview with well-signaled one-level-deep references and exceeds anchor 4, which allows minor organization gaps. | 5 / 5 |
Total | 17 / 20 Passed |