Content
92%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.
This is a strong, highly executable skill body: correct isolation model, explicit safety assertions, self-testing scripts, and clean one-level-deep references. Its only real weakness is mild token bloat from tangential sections (dev-build detection, web-terminal visual QA) and repeated safety guarantees that could be consolidated into a reference file.
Suggestions
Move the web-terminal visual QA walkthrough and the `bun run install:codex-dev` dev-build detection paragraph into a reference file (e.g. references/visual-qa.md), leaving a one-line pointer in the body to cut tangential tokens.
State the 'real ~/.codex is shasum-verified unchanged' guarantee once in the golden rules and drop its repetition in the scripts index and elsewhere.
Document the `--plugin` flag for scripts/tui-smoke.sh in the scripts index (the body references `tui-smoke.sh --plugin` but the index only describes its `--self-test`).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient and assumes competence (no explanation of what codex or tmux is; commands given directly), but there is trimmable material: the `bun run install:codex-dev` dev-build detection paragraph is tangential to the QA flow, the web-terminal visual QA section is detailed enough to belong in a reference file, and the 'real `~/.codex` unchanged' guarantee is repeated across the golden rules, scripts index, and elsewhere. These are minor instances of over-explanation, matching the score-4 anchor rather than the lean score-5 anchor. | 4 / 5 |
Actionability | Guidance is copy-paste ready throughout: `bash scripts/lib/common.sh --self-check`, a router table giving the exact script and flag per case (`scripts/app-server-drive.sh --plugin`, `scripts/hook-unit-probe.sh --self-test`, etc.), and an evidence-capture block with real commands (`ev=".omo/evidence/$(date +%Y%m%d)-codex-qa-<slug>"; mkdir -p "$ev"` plus two full script invocations). The router covers the common cases and the manual fallback rule (`export CODEX_HOME="$(mktemp -d)/codex"`) is executable as written. | 5 / 5 |
Workflow Clarity | The flow is clearly sequenced — setup self-check, router by need, matching QA to change scope, then evidence capture — with explicit validation checkpoints: each script's `--self-test` 'asserts its scenario against the live machine', every script 'shasums `~/.codex/config.toml` before and after and asserts it unchanged', and the hard rule 'no evidence file == the QA did not happen'. These are genuine feedback loops (assert → capture evidence → fail loudly), matching the top anchor. | 5 / 5 |
Progressive Disclosure | The SKILL.md body is a well-signaled overview with a router table linking each case to one-level-deep references, and all six linked files (isolation.md, app-server.md, docker-qa.md, install-verify.md, components-hooks.md, logging-debug.md) actually exist in the bundle alongside the referenced scripts. Content is appropriately split: decisions and commands inline, deep dives in references — matching the clear-overview anchor. The only blemish is that a few repo-level paths (script/agent/qa-docker.sh, docs/reference/web-terminal-visual-qa.md) point outside the skill bundle, but the in-bundle structure itself is exemplary. | 5 / 5 |
Total | 19 / 20 Passed |