Feedback on your jira skill

[RichardHightower]

I took a look at your jira skill and wanted to share some thoughts.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 82/100, solid B-grade territory. This is graded against Anthropic's skill best practices. Your strongest area is Spec Compliance (13/15) — the YAML frontmatter and trigger phrases are clean. Weakest pull is Writing Style (7/10) — some marketing speak creeping in where you need pure instruction, and a few voice consistency issues.

What's Working Well

• Trigger phrase coverage is excellent. You've nailed the discovery side with specific phrases like "create JIRA ticket," "search JIRA," "sprint planning." That's exactly what makes skills discoverable.
• Reference architecture is thoughtfully layered. The hub-and-spoke pattern (382-line SKILL.md + two references) is the right call. You're delegating weight appropriately instead of bloating the main file.
• Custom field discovery methodology is genuinely useful. This isn't just JIRA documentation — it's solving a real problem that teams actually hit. The workflow-based approach to discovering custom fields is the kind of thing that makes a skill valuable beyond obvious use cases.
• Issue templates in JSON are practical. Having 10 templated examples gives people concrete starting points instead of forcing them to figure out field structure from scratch.

The Big One: Architecture Inefficiency

Your jql_guide.md is oversized at 1323 lines — that's too much weight in a single reference file. This hurts your Progressive Disclosure score (22/30) because it forces users to parse a monolithic chunk instead of navigating focused sub-documents.

The fix: Split it into topic-specific guides:

• jql_basics.md — Simple queries, AND/OR operators
• jql_sprints_epics.md — Sprint/epic-specific queries
• jql_advanced.md — Complex logic, performance tips
• Keep jql_guide.md as an index that links to the others

This gets you +2 points immediately (brings PDA to 24/30) and makes the skill more scannable.

Other Things Worth Fixing

1. Remove marketing language. "intelligent JIRA management capabilities" reads like copy. Rephrase to: "Create and manage issues with field validation, search issues using JQL, handle custom fields." Direct, instructional, no fluff. (+1 point)

2. Add TOC to custom_field_discovery.md. At 258 lines, it needs navigation. One quick TOC section after the intro brings it up to standard. (+2 points)

3. Tighten second-person voice. SKILL.md has scattered "you" and "your" ("You need..."). Use passive construction: "Required for these operations" instead. Small but consistent issue. (+1 point)

4. Add verification checklists to workflows. Your issue creation steps are numbered but lack explicit checkpoints. Add: [ ] Project exists [ ] Fields validated [ ] Issue created [ ] Response verified. Helps users catch errors. (+1 point)

Quick Wins

• Split JQL guide into 4 focused docs (+2 points)
• Remove marketing phrases, pure instruction voice (+1 point)
• Add TOC to custom_field_discovery (+2 points)
• Verification checklists on workflows (+1 point)

These alone get you to 88/100, A-grade territory.

---

Checkout your skill here: SkillzWave.ai | SpillWave We have an agentic skill installer that installs skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.