Content
81%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.
Highly actionable and workflow-safe: executable commands throughout, exact error messages and workarounds, and a sequenced story-creation pattern with validation checkpoints and per-failure error-recovery paths. The main weakness is token efficiency — eight verbatim guard invocations and a duplicated verification block — plus a body long enough that some sections belong in reference files.
Suggestions
Replace the eight verbatim repetitions of the jira-site-guard.sh invocation with one defined guard snippet in the Authentication section and a one-line instruction to prepend it to every mutating acli command.
Deduplicate the JQL parent/label verification block — state it once (e.g., in 'Capturing created issue keys') and cross-reference it from 'Known limitations' instead of repeating both commands twice.
Move the auth-guard internals and the link-direction semantics ('--in is the BLOCKER, --out is the BLOCKED issue' plus read-back inversion) into a reference file to shorten the SKILL.md body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly operational with no padded conceptual explanations, but noticeable duplication: the '[ -x "${CLAUDE_PLUGIN_ROOT:-}/scripts/jira-site-guard.sh" ] ...' guard line appears verbatim 8+ times, and the JQL parent/label verification commands are repeated in both 'Known limitations' and 'Capturing created issue keys'. Matches the 3 anchor ('mostly efficient but ... could be tightened'); not 4 because the repetition is more than minor, and not 2 because there is no over-explanation of concepts Claude already knows. | 3 / 5 |
Actionability | Every section provides copy-paste-ready executable commands with exact flags, jq pipelines, the bulk JSON schema, and literal error messages (e.g. '✗ Error: Please select valid parent issue.'). Fully executable with the common cases covered — matches the 5 anchor. | 5 / 5 |
Workflow Clarity | 'Workflow pattern for story creation' gives a 7-step ordered sequence with step 4 'Capture returned issue keys' plus a jq key-extraction snippet, post-write verification via JQL ('confirm the story is parented'), and a dedicated error-handling section with recovery paths per failure mode (DNS block, auth, project/parent not found, rate limit). Clear sequence with explicit validation steps and error-recovery feedback loops — matches the 5 anchor; the batch-operation validation cap does not apply because verification is present. | 5 / 5 |
Progressive Disclosure | Good structure with clear section headers, and the ADF detail is properly split out behind a bold, clearly signaled one-level reference ('Before writing any description or comment to Jira, read .claude/refs/jira-adf.md'). Minor gaps: the ~320-line body inlines content (auth-guard internals, link-direction semantics, known limitations) that could live in reference files — matches the 4 anchor; not 5 because the split is only partial. | 4 / 5 |
Total | 17 / 20 Passed |