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-engineered skill body: executable worked examples, explicit validation checkpoints on every batch and CI workflow, and a clean worked-primary-plus-deep-dives structure that matches its bundle. The remaining gaps are minor — a few undefined helper calls, a referenced script absent from the bundle, and two reference files stranded two hops deep without a SKILL.md pointer.
Suggestions
Add taxonomy.md and tracker-vocabulary-map.md to the References section (or link them from the overview's tracker-agnostic rules) so all eight bundle files are discoverable one level deep from SKILL.md.
Define or inline the add_comment() and timestamp() helpers used by create_or_attach, and clarify whether scripts/file-jira-bug.py exists in the bundle or is to be authored from the helpers above.
Tighten repetition: the dedupe-before-create and never-hard-code-lifecycle-identifier rules each appear in the overview, the worked sections, and the anti-patterns table; state each fully once and cross-reference elsewhere.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly lean, high-value platform specifics Claude cannot be assumed to know ("description must be Atlassian Document Format (ADF), not plain text", "statusCategory != Done", per-platform rate limits, the dry-run gate). Minor trimming opportunities keep it below 5: the Basic-auth construction is boilerplate Claude already knows, and the dedupe-before-create and never-hard-code-identifiers rules are each restated three to four times across the overview, worked sections, and anti-patterns table. | 4 / 5 |
Actionability | Concrete, executable Python against real endpoints (POST /rest/api/3/issue, transitions lookup-and-apply, JQL search), a runnable CI YAML excerpt, and exact payload shapes like {"transition": {"id": "<id>"}}. Not 5 because create_or_attach calls add_comment() and timestamp() that are never defined, and the CI wiring invokes scripts/file-jira-bug.py which is not in the bundle — copy-paste readiness breaks at those points. | 4 / 5 |
Workflow Clarity | Every composite workflow carries an explicit "Verify:" checkpoint with feedback loops: the idempotent create must "return 0 open matches before create_bug fires" and fails closed on search error; the bulk transition requires a DRY_RUN pass where you "assert the dry-run count and keys match the issue set" and "fix the JQL and re-run" on mismatch; CI filing verifies a 2xx and non-empty key, with 400/429 recovery paths and a keep-it-red fallback. This batch-heavy skill has validation everywhere, so no cap applies. | 5 / 5 |
Progressive Disclosure | Good split: a worked Jira primary inline (with jira.md explicitly holding the remainder: "Auth setup, create, transition, and JQL search stay in SKILL.md"), clearly summarized one-link-deep deep dives for the other three trackers, and a descriptive References section — all six linked files exist. Not 5 because two bundle files (references/taxonomy.md and references/tracker-vocabulary-map.md) are never referenced from SKILL.md and are only reachable via a second hop through severity-vs-priority.md/lifecycle.md, burying them from discovery. | 4 / 5 |
Total | 17 / 20 Passed |