jira-mapper

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

Links:

• GitHub
• SkillzWave Marketplace

The Score

You're at 80/100, solid B-grade territory. This is based on Anthropic's skill best practices rubric. Your strongest area is Ease of Use (23/25) — the workflow steps are clear and well-numbered. The main drag is Progressive Disclosure Architecture (15/30) — you're putting everything into one file when it should be layered out.

What's Working Well

• Metadata is dialed in (9/10) — Your name format is correct hyphen-case, and the description with trigger terms for JIRA operations makes it discoverable
• Workflow clarity is solid — The numbered steps walk through mapping operations with appropriate constraints and validation points
• Good utility (17/20) — You're solving a real gap in SpecWeave-JIRA integration with proper error handling and feedback loops
• Bonus points for copy-paste checklists, grep-friendly structure, and exemplary examples — those details matter

The Main Thing: Missing Reference Files (High Priority)

Here's what's eating 7+ points: Your SKILL.md mentions a references/ directory with files like jira-concepts.md, specweave-concepts.md, and mapping-examples.md, but they don't actually exist. This breaks the layered architecture pattern that keeps long skills scannable.

Fix: Either create those reference files and link to them properly, or remove the references from your frontmatter. Since your SKILL.md is 500+ lines, you have room to extract this:

1. Create references/jira-concepts.md — JIRA hierarchy (epics/stories/subtasks), field mappings
2. Create references/specweave-concepts.md — SpecWeave increment types and structure
3. Create references/mapping-examples.md — Real mapping scenarios with before/after

Then reference them from SKILL.md sections with "See mapping-examples.md for detailed scenarios."

Impact: +7 points straight up.

Other Quick Wins

1. Add trigger phrases to description (currently missing them) — Change from a narrative description to: "Use when asked to 'map jira', 'jira mapper', 'map to epics', or 'sync increments to jira'"

2. Add a table of contents — With 500+ lines, throw a ## Quick Navigation section at the top pointing to each major section. Gets you +2 points on navigation_signals

3. Frontmatter polish — Add optional fields like tags: ["jira", "integrations", "project-management"] and categories: ["integration", "workflow"] to improve discoverability

Summary

You've got a well-structured skill with clear workflows and real utility. The heavy lift is creating those reference files to distribute your content. That single change bumps you from 80 to 87, which moves you solidly into A-territory. Then the trigger phrases and TOC get you over 90.

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