JIRA Assistant Skills

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

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

"Show my high priority sprint work"

Time Saved

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-as>=1.1.3"  # jira-as CLI + shared library from public PyPI

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="you@company.com"
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-as issue get PROJ-123
jira-as search query "project = PROJ AND status = Open"
jira-as time log PROJ-123 --time 2h

That's it. Claude now has full JIRA access via natural language, and you can use the jira-as 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

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="you@company.com"
   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

Skills Overview

Full CLI Reference →

Who Is This For?

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

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

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

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

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

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

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

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

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

"Create urgent incident: Production database unreachable"

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

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

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
• Layered Config — Env vars, system keychain, and settings files
• ADF Support — Native Atlassian Document Format handling
• Exponential Backoff — Automatic retry on rate limits

Quality & Security

Test Coverage

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

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 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

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-as>=1.1.3" pytest pytest-asyncio
pip install -e .  # Install the plugin package in editable mode

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

# Verify CLI is working
jira-as --version
jira-as --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.}