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.
The body is exceptionally actionable with a well-validated workflow, but it reads as a monolithic reference: scheduler internals duplicating the bundled script, duplicated rationale sections, and repo-migration history inflate the token cost. Splitting implementation detail into references/ and cutting the history would raise both conciseness and disclosure scores without losing executable guidance.
Suggestions
Move the scheduler-internal sections (Job State Machine, OOM Handling, Stale Screen Detection, Resume-on-restart) into a references/scheduler-internals.md file, since they describe behavior already implemented in scripts/queue_manager.py; keep SKILL.md as the operator-facing workflow overview.
Collapse Step 3a to a short rule ("use $CLAUDE_SKILL_DIR/scripts if present, else tools/experiment_queue") and delete the Phase 3.3 / Arch C / shim-provenance narrative and issue-number citations — they document repo history, not what the operator must do.
Merge "Why This Exists" with "Rationale / Source" (they repeat the same 2026-04-16 audit) and drop the feature-comparison table, whose content is already covered by "When to Use This Skill" and the closing rule about ≤5 vs ≥10 jobs.
Either bundle the two referenced shared-references files (external-cadence.md, compute-env-contract.md) inside the skill or summarize their operative rules inline, since the links currently point outside the skill directory and cannot be resolved from the bundle.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~430-line body is mostly dense, non-obvious instruction (path forms for scp vs ssh, resume semantics, state-file caveats), but carries clear padding: "Why This Exists" and "Rationale / Source" repeat the same audit findings, the comparison table restates "When to Use"/"Key Rules", and Step 3a narrates repo migration history ("Phase 3.3 move, Arch C", issue numbers #174/#366, shim provenance) that Claude cannot act on. This sits between the 'mostly efficient' (3) and 'efficient, minor trimming' (4) anchors, but the volume of duplicated and historical material pulls it to 3. | 3 / 5 |
Actionability | Nearly everything is copy-paste executable: the PROJECT_DIR/RUN_TS bootstrap with a guarded placeholder, the full QUEUE_TOOLS resolution chain with an explicit error message, the scp-vs-ssh path distinction with working commands, the nohup launch, the jq status query, and the run_meta.txt persistence using printf %q. Only routine placeholders (<server>) need substitution, which the skill flags in place. | 5 / 5 |
Workflow Clarity | Steps 1–5 are clearly sequenced with explicit validation checkpoints: pre-flight (SSH, conda env, cwd, preconditions, GPU availability) that reports blocked jobs, expected-output-based completion rather than trusting screen state, bounded OOM retry as a feedback loop, stale-screen detection every 60s, and idempotent resume-on-restart. Error-recovery paths (resume without re-running bootstrap, stale state file from the 2026-08 fix) are called out explicitly. | 5 / 5 |
Progressive Disclosure | Section headers are good and the two scripts/ bundle files (queue_manager.py, build_manifest.py) are real and correctly referenced, but the body inlines scheduler internals that duplicate the script — the job state machine, Stale Screen Detection, OOM Handling, and Resume-on-restart algorithms are already implemented in queue_manager.py and belong in a references/ file. The two "../shared-references/*.md" links point outside the skill directory and are not present in this bundle, so navigation to them cannot be confirmed. This matches 'some structure; content that should be separate is inline' rather than the level-4 anchor, where most content is appropriately split. | 3 / 5 |
Total | 16 / 20 Passed |