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.
A well-structured, tracker-agnostic skill body with genuinely executable Jira code, thorough validation checkpoints (fail-closed dedupe, dry-run bulk gating, HTTP error recovery), and sensible per-platform reference files. The main gaps are the missing referenced CI script, an add_comment call undefined for the Jira path, and some rule repetition that could be tightened.
Suggestions
Add or remove the scripts/file-jira-bug.py reference: the CI integration section instructs 'python scripts/file-jira-bug.py results.xml' but no scripts/ directory exists in the bundle, so the step cannot be executed as written.
Define add_comment (and timestamp) for the Jira path — create_or_attach depends on them but they are only implemented in references/github-issues.md and references/azuredevops.md, not in the body or references/jira.md.
Link taxonomy.md and tracker-vocabulary-map.md directly from the References section of SKILL.md so they are discoverable without traversing severity-vs-priority.md, and consolidate the repeated dedupe / no-hard-coded-IDs rules into one authoritative section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body sticks to platform-specific API detail Claude does not inherently know (ADF payloads, runtime transition lookup, WIQL, JSON Patch) rather than generic concepts, but key rules ('dedupe before create', 'never hard-code transition IDs') are each restated 2-3 times across the Overview, Verify paragraphs, and the Anti-patterns table. Efficient with minor trimming opportunities — anchor 4, not anchor 5's every-token-earns-its-place. | 4 / 5 |
Actionability | Mostly executable, copy-paste-ready code (create_bug, get_transitions, transition, search_jql, DRY_RUN bulk loop, CI YAML), but create_or_attach calls add_comment and timestamp, which are never defined for Jira (only in the GitHub and ADO references), and the referenced scripts/file-jira-bug.py does not exist in the bundle. Minor gaps keep it below anchor 5. | 4 / 5 |
Workflow Clarity | Multi-step workflows carry explicit 'Verify:' checkpoints and feedback loops: search must return 0 open matches before create (fail closed on search error), dry-run count/keys verified before DRY_RUN flips to False, HTTP 2xx + non-empty issue key asserted, and 400 (fix ADF payload and re-run) / 429 (back off and retry) recovery paths. The batch-operation validation requirement is fully met, matching anchor 5. | 5 / 5 |
Progressive Disclosure | A clear overview table routes each platform to an existing one-level-deep reference file and the Jira worked example is appropriately inlined as the primary. However, scripts/file-jira-bug.py is referenced but missing from the bundle, and taxonomy.md and tracker-vocabulary-map.md are only reachable via second-level links from severity-vs-priority.md/lifecycle.md — minor organization gaps that hold it below anchor 5. | 4 / 5 |
Total | 17 / 20 Passed |