jira-assistant-skills 2.2.5

A collection of CLI-based assistant skills for interacting with Jira.

JIRA Assistant Skills

10x More context-efficient than MCP servers

14 Specialized skills one conversation

245 Production-ready Python scripts

0 JQL syntax to memorize

Natural language JIRA automation for Claude Code
_{From sprint planning to incident response—14 skills, 245 scripts, zero JQL memorization.}

┌───────────────────────────────────────────────────────────────┐
│ You: "What's blocking the Q4 release?"                        │
├───────────────────────────────────────────────────────────────┤
│ Claude: Analyzing 147 issues across 3 projects...             │
│                                                               │
│ Found 4 blockers:                                             │
│ • PLATFORM-234: API rate limiting (blocked 12 issues)         │
│ • MOBILE-567: iOS signing certificate expired                 │
│ • WEB-890: Pending security review                            │
│ • INFRA-123: Database migration not scheduled                 │
│                                                               │
│ Recommended actions:                                          │
│ 1. Escalate PLATFORM-234 to @api-team (highest impact)        │
│ 2. MOBILE-567 can be resolved by @devops today                │
│ 3. WEB-890 needs @security-lead approval                      │
└───────────────────────────────────────────────────────────────┘

Get Started • Skills • Use Cases • Architecture

---

The Difference

❌ The JQL Way project = PROJ AND status IN ("To Do", "In Progress") AND assignee = currentUser() AND sprint IN openSprints() AND priority IN (High, Highest) ORDER BY priority DESC, created ASC Hope you remembered the syntax...

✅ The Natural Way "Show my high priority sprint work" Just ask.

Time Saved

Task	Traditional JIRA	JIRA Assistant	Saved
Find my open bugs	45 seconds	5 seconds	89%
Create sprint + add stories	3 minutes	15 seconds	92%
Log time on 5 issues	2 minutes	20 seconds	83%
Check what's blocking release	5 minutes	10 seconds	97%
Bulk close 20 resolved issues	4 minutes	30 seconds	88%

Typical developer: Save 30+ minutes per week. Team of 8: Reclaim 31 work days per year.

---

Quick Start

1. Clone the Repository

git clone https://github.com/grandcamel/jira-assistant-skills.git
cd jira-assistant-skills

2. Install Dependencies

pip install jira-assistant-skills-lib
pip install -e .  # Install the jira CLI

3. Get API Token

1. Visit Atlassian API Tokens
2. Create token → Copy it

4. Configure

export JIRA_API_TOKEN="your-token"
export JIRA_EMAIL="[e-mail]"
export JIRA_SITE_URL="https://company.atlassian.net"

5. Start Using

# Just ask Claude
claude "Show me my open issues"
claude "Create a bug: Login button not working"
claude "What's blocking the release?"

# Or use the CLI directly
jira issue get PROJ-123
jira search query "project = PROJ AND status = Open"
jira time log PROJ-123 2h

That's it. Claude now has full JIRA access via natural language, and you can use the jira CLI directly from your terminal.

Full Setup Guide →

---

Setup (Assistant Skills)

If you're using the Assistant Skills plugin system, run the setup wizard:

/assistant-skills-setup

This configures:

• Shared Python venv at ~/.assistant-skills-venv/
• Required dependencies from requirements.txt
• Environment variables (prompts you to configure Jira credentials)
• claude-as shell function for running Claude with dependencies

After setup, use claude-as instead of claude:

claude-as  # Runs Claude with Assistant Skills venv activated

Environment Variables

Variable	Required	Description
JIRA_SITE_URL	Yes	Jira instance base URL (e.g., https://company.atlassian.net)
JIRA_EMAIL	Yes	Atlassian account email for authentication
JIRA_API_TOKEN	Yes	Atlassian API token (generate here)
JIRA_PROFILE	No	Configuration profile for multi-instance support (defaults to production)

Getting Your API Token

1. Go to Atlassian API Tokens
2. Click "Create API token"
3. Give it a descriptive label (e.g., "Claude Code Jira")
4. Copy the token and add it to your shell config:

   export JIRA_API_TOKEN="your-token-here"
   export JIRA_EMAIL="[e-mail]"
   export JIRA_SITE_URL="https://company.atlassian.net"
   

---

What You Can Do

flowchart LR
    subgraph Input["💬 You Say"]
        Q1["Show my high<br/>priority bugs"]
        Q2["Create a story<br/>for login redesign"]
        Q3["What's blocking<br/>the release?"]
    end

    subgraph Processing["🤖 Claude Understands"]
        P1["JQL: assignee=currentUser()<br/>AND type=Bug<br/>AND priority>=High"]
        P2["create_issue.py<br/>--type Story<br/>--summary '...'"]
        P3["Search linked blockers<br/>Traverse dependency tree"]
    end

    subgraph Output["✅ You Get"]
        R1["📋 List of 7 bugs<br/>with details"]
        R2["🎫 PROJ-456 created<br/>ready to refine"]
        R3["🔍 3 blockers found<br/>with recommendations"]
    end

    Q1 --> P1 --> R1
    Q2 --> P2 --> R2
    Q3 --> P3 --> R3

📖 Example: Sarah's Monday Morning

Before JIRA Assistant (15 minutes)

1. Open browser, navigate to JIRA (2 min)
2. Find the right board (1 min)
3. Set up filters (3 min)
4. Check each issue status (5 min)
5. Look up sprint velocity (2 min)
6. Copy issues to notes (2 min)

After JIRA Assistant (45 seconds)

Sarah: "What's my sprint work and yesterday's progress?"

Claude provides a formatted summary with everything she needs.

Time saved: 14 minutes per standup × 250 days = 58 hours/year

---

Skills Overview

Skill	Purpose	Example Command
jira-assistant	Meta-skill router	Routes to the right skill automatically
jira-issue	Issue CRUD	"Create a bug for login failure"
jira-lifecycle	Workflow transitions	"Move PROJ-123 to In Progress"
jira-search	JQL & filters	"Show my open issues"
jira-collaborate	Comments & watchers	"Add comment to PROJ-123"
jira-agile	Sprints & epics	"Create sprint for next week"
jira-relationships	Issue linking	"What's blocking PROJ-123?"
jira-time	Time tracking	"Log 2 hours on PROJ-123"
jira-jsm	Service desk	"Show my support queue"
jira-bulk	Bulk operations	"Close all resolved issues"
jira-dev	Git integration	"Generate branch name for PROJ-123"
jira-fields	Field discovery	"Show custom fields in PROJ"
jira-ops	Cache & utilities	"Clear JIRA cache"
jira-admin	Project admin	"List project permissions"

Full Scripts Reference →

---

Who Is This For?

👨‍💻 Developers — Never leave your terminal

Stop context-switching to JIRA.

You're in your IDE. You just fixed a bug. Now you need to update JIRA.

claude "Close PROJ-123 with 'Fixed null pointer', log 30 minutes"
# 3 seconds, never left your terminal

Developer Cheat Sheet

Task	Command
Check my work	"What's assigned to me in the current sprint?"
Start a task	"Start progress on PROJ-123"
Log time	"Log 2 hours on PROJ-123: Implemented auth fix"
Mark done	"Close PROJ-123 with resolution Fixed"
Create bug	"Create high priority bug: Login fails on Safari"
Get branch name	"Generate branch name for PROJ-123"

Time saved: ~45 min/week

👥 Team Leads — Team visibility in seconds

See your team's work without meetings.

Morning Check-in (60 Seconds)

"Show sprint progress for Team Alpha"
"Who has the most work in progress?"
"What's blocked and why?"

Sprint Planning Support

"Show unestimated stories in backlog"
"What's the team velocity for last 3 sprints?"
"Move top 10 priority items to Sprint 42"

Query Templates

Need	Command
Blockers	"Show blockers across all team projects"
Workload	"Who's overloaded? Show assignment counts"
Progress	"What moved to Done yesterday?"
Export	"Export this sprint's completed work to CSV"

Time saved: ~4 hours/week

🏃 Scrum Masters — Run ceremonies, not admin

Focus on facilitation, not JIRA navigation.

Sprint Planning (Before)

"Show prioritized backlog with estimates"
"What dependencies exist in top 20 items?"
"Create Sprint 43 starting next Monday"

Daily Standup (During)

"Show yesterday's progress for Sprint 43"
"What's blocked right now?"
"Who has items without updates > 24 hours?"

Sprint Review (After)

"Show completed items in Sprint 43 by epic"
"Export sprint results for stakeholder presentation"
"What carried over from last sprint?"

Time saved: ~4.5 hours/sprint

📊 Product Managers — Self-serve product data

Focus on product, not project administration.

Roadmap Management

"Show all epics for Q1 with completion percentage"
"What features shipped last month?"
"Create epic: User Authentication Redesign"

Backlog Grooming

"Show stories without acceptance criteria"
"What's been in backlog > 90 days?"
"Prioritize FEAT-123 above FEAT-124"

Stakeholder Communication

"Export release notes for v2.1"
"Summarize what's shipping this sprint"
"Show bug fix rate for last quarter"

Time saved: ~5 hours/week

🔧 IT/Ops — Incident response accelerated

Incident response without the JIRA dance.

Incident Creation (10 Seconds)

"Create urgent incident: Production database unreachable"

Creates P1 with proper labels and assigns to on-call.

Incident Management

"Show all open incidents by severity"
"Link INCIDENT-123 to root cause INFRA-456"
"Escalate INCIDENT-123 to @platform-team"

Service Desk (JSM)

"Show my queue sorted by SLA breach time"
"Resolve REQ-789 with 'Password reset completed'"
"Add customer to watchers on REQ-789"

Time saved: Minutes per incident

---

Architecture

flowchart TD
    U["👤 User Request"] --> CC["🤖 Claude Code"]
    CC --> JA["📋 jira-assistant<br/>Meta-Router"]

    JA -->|"Create bug"| JI["jira-issue"]
    JA -->|"Move to Done"| JL["jira-lifecycle"]
    JA -->|"Find issues"| JS["jira-search"]
    JA -->|"Add comment"| JC["jira-collaborate"]
    JA -->|"Link issues"| JR["jira-relationships"]
    JA -->|"Sprint planning"| JAG["jira-agile"]
    JA -->|"Log time"| JT["jira-time"]
    JA -->|"Bulk update"| JB["jira-bulk"]
    JA -->|"Service request"| JSM["jira-jsm"]

    JI & JL & JS & JC & JR & JAG & JT & JB & JSM --> SH["🔧 Shared Library"]
    SH --> API["🔌 JIRA REST API"]
    API --> JIRA[("☁️ JIRA Cloud")]

Technical Highlights

• Shared Library Pattern — DRY architecture with common utilities
• 4-Layer Error Handling — Validation → API → Retry → User messages
• Profile-Based Config — Multi-instance support built-in
• ADF Support — Native Atlassian Document Format handling
• Exponential Backoff — Automatic retry on rate limits

---

Quality & Security

Test Coverage

Category	Tests	Description
Core Skills	850+	Issue, search, lifecycle, collaborate, agile, relationships, time
JSM Integration	150+	Service desks, SLAs, approvals, knowledge base
Advanced Skills	300+	Bulk ops, dev workflows, fields, cache, admin
Live Integration	340+	End-to-end tests against real JIRA instances
Total	1644	All passing

Tests run against live JIRA Cloud instances to ensure real-world reliability.

Security

• No hardcoded secrets — API tokens stored in environment variables or gitignored files
• HTTPS-only connections — All JIRA API requests enforced over secure transport
• Input validation — All user data validated before API calls
• Credential isolation — settings.local.json gitignored by default
• No credential logging — Sensitive data excluded from logs and error output

---

Try It

One-click cloud environment with all dependencies pre-installed.

---

Documentation

Resource	Description
Quick Start Guide	Get up and running in 5 minutes
Configuration Guide	Multi-profile setup and options
Scripts Reference	Complete CLI documentation
Troubleshooting	Common issues and solutions

Need Help?

• 💬 GitHub Discussions
• 🐛 Report Issues

---

E2E Testing

Run E2E Tests

E2E tests validate the plugin with the Claude Code CLI:

# Requires ANTHROPIC_API_KEY
./scripts/run-e2e-tests.sh           # Docker
./scripts/run-e2e-tests.sh --local   # Local

See tests/e2e/README.md for details.

Sandboxed Container Testing

Run tests with restricted tool access for safe demos and focused testing:

cd plugins/jira-assistant-skills/skills/jira-assistant/tests

# Safe demo mode (view/search only)
./run_sandboxed.sh --profile read-only

# JQL-focused testing
./run_sandboxed.sh --profile search-only

# Issue CRUD only
./run_sandboxed.sh --profile issue-only

Profile	Use Case	What's Allowed
read-only	Safe demos, evaluations	View issues, search, list fields
search-only	JQL training	Search queries only
issue-only	CRUD workshops	Issue operations only
full	Complete testing	All operations

---

Contributing

Contributions are welcome! See our Contributing Guide.

# Clone the repository
git clone https://github.com/grandcamel/jira-assistant-skills.git
cd jira-assistant-skills

# Install dependencies and CLI
pip install jira-assistant-skills-lib>=0.1.5 pytest pytest-asyncio
pip install -e .  # Install CLI in editable mode

# Run tests (uses root pytest.ini configuration)
pytest plugins/jira-assistant-skills/skills/*/tests/*.py -v

# Verify CLI is working
jira --version
jira --help

---

Roadmap

• Core JIRA operations (v1.0)
• Agile workflow support (v1.1)
• Service Management (v1.2)
• Bulk operations (v1.3)
• GitHub integration enhancements
• Slack notifications
• Custom workflow templates

---

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Stop clicking through JIRA. Start talking to it.
_{Built for Claude Code by developers who were tired of memorizing JQL.}