Content
75%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 well-built instruction skill: executable commands with a path guard, an explicit confirm-before-overwrite checkpoint for the one destructive operation, enumerated profile fields, and honest limits around small samples, consent, and untrusted sample data. The consistent gaps are minor: no concrete example invocation, no post-generation validation step, and reference navigation that requires parsing a dense path-substitution paragraph.
Suggestions
Add one concrete example invocation with realistic arguments (e.g., `python3 "$BLOG_SCRIPT_DIR/style_learn.py" posts/*.md --format markdown`) and name the actual flag behind the "requested minimum sample count" so the commands are fully copy-paste ready.
Convert the prose reference to `orchestration-details.md` into a standard markdown link and simplify or move the host path-substitution rules so the reference is reachable without parsing the dense opening paragraph; verify the referenced file actually ships with the skill bundle.
Add a light validation step after profile generation (e.g., sanity-check that sentence-length mean and type-token ratio are plausible before writing VOICE.md) to close the workflow's only remaining feedback-loop gap.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient: it never explains concepts Claude already knows, and the limits section (small-sample instability, consent, untrusted sample data) earns every token. It sits at anchor 4 rather than 5 because of minor trims available — e.g., "The profile captures measurable style signals so future drafts can preserve the author's cadence, vocabulary, and tone" largely restates the opening — but it is clearly above anchor 3, which requires unnecessary explanation or padding. | 4 / 5 |
Actionability | It provides real, executable bash commands with a path-resolution guard (the `case "$BLOG_SCRIPT_DIR"` absolute-path check), three concrete invocations for markdown/json/VOICE.md output, enumerated profile fields, and per-failure error handling — squarely anchor 4. It misses anchor 5 because `<paths>` is never shown in a concrete example invocation and the "requested minimum sample count" is never tied to an actual flag; it is above anchor 3 because the commands are executable, not pseudocode. | 4 / 5 |
Workflow Clarity | The sequence (gather 5–10 samples → run the learner → choose output format → drop into VOICE.md or feed blog-persona) is clear, and the one destructive operation has an explicit checkpoint: "if VOICE.md already exists, write to voice-profile.md first, show the user a diff, and overwrite only after they confirm", with an Error Handling section covering the batch's failure modes (skip + warn). It is anchor 4 rather than 5 because there is no post-generation validation step (e.g., sanity-check the profile before consuming it) and the sequence is not explicitly numbered; it is above anchor 3 because checkpoints for the destructive overwrite and batch failures are present, not missing. | 4 / 5 |
Progressive Disclosure | Sections are well-organized and appropriately sized for a SKILL.md overview, and references are one level deep and clearly signaled ("Read the main reference `orchestration-details.md` before loading project context"). It reaches only anchor 4, not 5, because the bundle ships no references/ or scripts/ directories — the referenced files resolve only through the convoluted sibling-directory substitution paragraph ("${CLAUDE_SKILL_DIR}/../blog/references"), and references are named in prose rather than linked, making navigation harder than the anchor-5 clear-link pattern. | 4 / 5 |
Total | 16 / 20 Passed |