Content
50%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 highly actionable — nearly every instruction is a runnable command — and workflows are clearly sequenced, but it is roughly twice the length a SKILL.md should be, with heavy example repetition and model/config catalogs inlined instead of split into reference files. Destructive bypass-mode batch workflows also lack validation checkpoints between steps, which caps workflow clarity despite good sequencing.
Suggestions
Cut the redundant flag examples: define '--dangerously-bypass-approvals-and-sandbox', '--full-auto', and the -a/-s options once in a reference table and use short forms elsewhere; consolidate the three overlapping model-selection sections into one.
Move the model catalog (with pricing/dates), full config.toml reference, and CI/CD example into references/ files (e.g., references/models.md, references/config.md) and link them from a concise overview; remove or verify the 'Related Skills' links that have no bundle files.
Add explicit validation checkpoints to destructive/batch workflows: e.g., after generate_api and automate_testing, diff/inspect changes and run a verification pass before proceeding, and document the --json output schema the jq pipelines depend on.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~685-line body is noticeably padded: the full flag '--dangerously-bypass-approvals-and-sandbox' is repeated in ~15 near-identical examples, model selection guidance appears in three sections ('Available Models', 'Model Selection Strategy', 'Troubleshooting'), and time-sensitive details (release dates, pricing, 'December 2025' sprinkled through headers) are inline rather than isolated. It does not explain basic concepts Claude already knows, so it stays above anchor 1, but the redundancy clearly matches anchor 2 ('several unnecessary... padded sections') rather than anchor 3's 'mostly efficient'. | 2 / 5 |
Actionability | Commands are concrete and copy-paste ready throughout (install, auth, exec invocations, config.toml, CI YAML), with the common cases covered. It falls short of anchor 5 because of minor gaps: the JSON workflows pipe '--json' output through jq with assumed schemas ('.functions[].name', '.changes[]') that are never documented, and some flags/outputs are asserted without verification steps. This is above anchor 3 since nothing is pseudocode and the guidance is executable. | 4 / 5 |
Workflow Clarity | Sequences are clear (Think-Act-Observe loop, six-step OAuth decomposition, refactor with git-stash rollback), and a 'Security with Bypass Mode' section adds backups/scope-limiting. But most destructive/batch workflows (generate_api, automate_testing, bulk .js-to-TypeScript conversion, 'Run tests and auto-fix all failures') fire with no validation checkpoint between steps, so the rubric's cap — destructive/batch operations without validation score at most 3 — applies. It is above anchor 2 because sequences are well defined and some checkpoints (plan review, rollback on failure) exist. | 3 / 5 |
Progressive Disclosure | Section headers give real structure, but the monolithic ~685-line file inlines content that clearly belongs in separate reference files (full model catalog with pricing, config.toml reference, CI/CD example, troubleshooting) and the bundle contains no reference files at all, while 'Related Skills' links (codex-auth, codex-chat, etc.) have no corresponding files. This matches anchor 3 ('content that should be separate is inline') — better than anchor 2's headerless wall, short of anchor 4 where most bulk content lives in separate, clearly signaled files. | 3 / 5 |
Total | 12 / 20 Passed |