Jira Integration Skill
Comprehensive Jira integration through lightweight Python CLI scripts.
Auto-Trigger Patterns
AUTOMATICALLY ACTIVATE when user mentions:
- Jira URLs:
https://jira.*/browse/*,https://*.atlassian.net/browse/*,https://*/jira/browse/* - Issue keys: Pattern like
PROJ-123,NRS-4167,ABC-1(uppercase letters + hyphen + numbers) - Keywords: "Jira issue", "Jira ticket", "search Jira", "open this ticket"
Example triggers:
- "I want to work on https://jira.netresearch.de/browse/NRS-4167" → Extract NRS-4167, fetch issue
- "What's the status of PROJ-123?" → Fetch issue PROJ-123
- "Search Jira for my open issues" → Run JQL search
Authentication Failure Handling
CRITICAL: When authentication fails, DO NOT just display the error. Instead:
- Detect failure - Look for "Missing required variable", "Configuration errors", or 401/403 responses
- Offer help - Ask: "Jira credentials aren't configured. Would you like me to help set them up?"
- Run interactive setup - Execute:
uv run skills/jira-communication/scripts/core/jira-setup.py - The script will:
- Prompt for Jira URL
- Auto-detect Cloud vs Server/DC
- Ask for credentials (API token or Personal Access Token)
- Validate credentials before saving
- Create
~/.env.jirawith secure permissions (600)
Sub-Skills
This plugin contains two specialized skills:
| Skill | Purpose |
|---|---|
jira-communication | API operations via Python CLI scripts |
jira-syntax | Wiki markup syntax, templates, validation |
Quick Start
# Install uv (Python package runner)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Configure credentials in ~/.env.jira
JIRA_URL=https://your-instance.atlassian.net
JIRA_USERNAME=your-email@example.com
JIRA_API_TOKEN=your-api-token
# Validate setup
uv run scripts/core/jira-validate.py --verbose
Common Operations
# Search issues
uv run scripts/core/jira-search.py query "project = PROJ AND status = 'In Progress'"
# Get issue details
uv run scripts/core/jira-issue.py get PROJ-123
# Add worklog
uv run scripts/core/jira-worklog.py add PROJ-123 "2h 30m" -c "Code review"
# Create issue
uv run scripts/workflow/jira-create.py issue PROJ "Fix bug" --type Bug --priority High
# Transition issue
uv run scripts/workflow/jira-transition.py PROJ-123 "In Progress"
Features
- Zero MCP overhead - Scripts invoked via Bash, no tool descriptions loaded
- Fast execution - No Docker container spin-up
- Full API coverage - All common Jira operations supported
- Jira Server/DC + Cloud - Works with both deployment types
- Automatic auth detection - API token, PAT, or basic auth
Sub-Skill Documentation
- skills/jira-communication/SKILL.md - API operations (scripts, JQL, worklogs)
- skills/jira-syntax/SKILL.md - Wiki markup syntax, templates, validation
Scripts Reference
Core Operations
| Script | Purpose |
|---|---|
jira-setup.py | Interactive credential setup (run when auth fails) |
jira-validate.py | Verify connection and credentials |
jira-issue.py | Get or update issue details |
jira-search.py | Search with JQL queries |
jira-worklog.py | Time tracking entries |
jira-comment.py | Add/list comments |
Workflow Operations
| Script | Purpose |
|---|---|
jira-create.py | Create new issues |
jira-transition.py | Change issue status |
jira-link.py | Create/list issue links |
jira-sprint.py | Sprint management |
jira-board.py | Board operations |
Jira Syntax Quick Reference
Important: Jira uses wiki markup, NOT Markdown.
| Jira Syntax | Purpose |
|---|---|
h2. Title | Heading (NOT ## Title) |
*bold* | Bold (NOT **bold**) |
{code:java}...{code} | Code block (NOT triple backticks) |
[text|url] | Link |
[PROJ-123] | Issue link |
See skills/jira-syntax/SKILL.md for complete syntax guide.
Contributing: Improvements to this skill should be submitted to the source repository: https://github.com/netresearch/jira-skill