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.
A lean, well-structured instruction skill: a command table with explicit per-command contracts, an exact authoring contract (paths, name regex, frontmatter shape), explicit validation checks, and a consistent ✓/✗ exit protocol. Its weaknesses are the reliance on a `templates/AGENTS.md` contract that is absent from the bundle and the absence of any other bundle files to carry detail progressively.
Suggestions
Ship `templates/AGENTS.md` (or whatever bundle directory holds it) with the skill, or inline the essential invariants — as written, the body delegates its core execution contract to a file the bundle does not contain.
Replace the generic "Run the authoring wizard" step with the wizard's actual prompt sequence so the add flow is executable from SKILL.md alone.
Merge the overlapping tail of "Validation and errors" into the "Exit contract" section to remove the duplicated ✓/✗ reporting guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient: a command-contract table, a compact authoring contract with the exact name regex, canonical roots with env-var expansion, and a tight exit contract — no explanations of concepts Claude already knows. Not a 5 because the two embedded templates (frontmatter and recommended body shape) and the slight overlap between the "Validation and errors" and "Exit contract" sections could still be trimmed. | 4 / 5 |
Actionability | Guidance is concrete throughout: exact paths ("${CODEX_HOME:-$HOME/.codex}/skills/", ".codex/skills/"), the name pattern "[a-z0-9]+(?:-[a-z0-9]+)*", per-command contracts, and a literal error format ("✗ Error: <clear message> / → Suggestion: <specific next step>"). Not a 5 because interactive flows like "Run the authoring wizard" are not specified in-skill — they are delegated to a contract file that is not present in the bundle. | 4 / 5 |
Workflow Clarity | Each command's contract sequences its steps, and validation is explicit: "confirm explicitly, then remove its directory", "never rewrite files", "Before reporting success, check that the file exists, starts with `---` frontmatter..." — a feedback loop for the destructive remove and batch validate cases. Not a 5 because recovery is specified as an error format rather than an explicit validate→fix→retry loop, and the shared execution/delegation invariants live in an external file. | 4 / 5 |
Progressive Disclosure | Sections are well organized and the body keeps shared invariants out-of-line ("Shared execution, delegation, state, hook, team, cancellation, verification, and escalation invariants live in `templates/AGENTS.md`"), but that referenced file does not exist anywhere in the skill bundle, leaving the only external reference dangling. The structure itself is good, which keeps this above a 2, but a broken/one-level reference the reader cannot resolve prevents a 4. | 3 / 5 |
Total | 15 / 20 Passed |