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 excels at actionability and workflow clarity with executable commands and strong validation feedback loops for credit-consuming, publish, and source operations. It loses points on conciseness due to repeated passages and on progressive disclosure because a large monolithic operational spec is inlined rather than split into reference files.
Suggestions
Deduplicate the `run advance` no-op / `awaiting_sources` guidance and the `materials_only` reminders so each rule appears once, then cross-references it.
Extract the freshness/update protocol and the source-upload lifecycle into separate reference files (e.g. UPDATE.md, SOURCES.md) and link to them from SKILL.md to improve progressive disclosure.
Move the long update-ratchet decision tree into a short checklist with the verbose branch table in a referenced file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes Claude's competence (no basic-concept padding), but it repeats the same guidance in multiple places — e.g. the `run advance` 200 no-op / `awaiting_sources` behavior is explained in both 'Build and submit the blueprint' and 'Finish, recover and report', and `materials_only` is reiterated several times — so it is 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than lean. | 3 / 5 |
Actionability | Provides fully executable, copy-paste-ready commands with concrete flags throughout ('personwise version --json', 'personwise --account <alias> course readiness --json', 'source add --run-id <run-id> --path <exact-path> --json', 'run wait --run-id <run-id> --timeout-seconds 1800 --json') and parameterizes the common cases, matching the top anchor. | 5 / 5 |
Workflow Clarity | The multi-step process (readiness → blueprint → sources → checkpoints → publish) is clearly sequenced with explicit validation checkpoints (`can_create=false` gating, `source status` polling until `ready`, review-at-`paused`, `--expected-revision`) and concrete feedback loops (retry once then stop on repeated error; `read_current_state` conflict → bounded retry → stop), matching the 'clear sequence with explicit validation steps; feedback loops' anchor. | 5 / 5 |
Progressive Disclosure | Section headers give the single SKILL.md some structure and the bundled assets (bootstrap.sh, bootstrap.ps1, service-descriptor.signed.json) are referenced one level deep, but the body is a long monolithic operational wall where sizable subprotocols (freshness/update handling, source lifecycle) are inlined rather than split into separate reference files, fitting 'some structure but could be better organized; content that should be separate is inline'. | 3 / 5 |
Total | 16 / 20 Passed |