jira-integration
netresearch/jira-skillAgent Skill: Comprehensive Jira integration through lightweight Python scripts. AUTOMATICALLY TRIGGER when user mentions Jira URLs like 'https://jira.*/browse/*', 'https://*.atlassian.net/browse/*', or issue keys like 'PROJ-123'. Use when searching issues (JQL), getting/updating issue details, creating issues, transitioning status, adding comments, logging worklogs, managing sprints and boards, creating issue links, or formatting Jira wiki markup. If authentication fails, offer to configure credentials interactively. Supports both Jira Cloud and Server/Data Center with automatic authentication detection. By Netresearch.
6 stars
2 forks
Python
13 views
SKILL.md
name: jira-integration description: "Agent Skill: Comprehensive Jira integration through lightweight Python scripts. AUTOMATICALLY TRIGGER when user mentions Jira URLs like 'https://jira./browse/', 'https://.atlassian.net/browse/', or issue keys like 'PROJ-123'. Use when searching issues (JQL), getting/updating issue details, creating issues, transitioning status, adding comments, logging worklogs, managing sprints and boards, creating issue links, or formatting Jira wiki markup. If authentication fails, offer to configure credentials interactively. Supports both Jira Cloud and Server/Data Center with automatic authentication detection. By Netresearch."
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
[email protected]
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
README
Jira Skill for Claude Code
Comprehensive Jira integration through lightweight Python scripts.
🔌 Compatibility
This is an Agent Skill following the open standard originally developed by Anthropic and released for cross-platform use.
Supported Platforms:
- ✅ Claude Code (Anthropic)
- ✅ Cursor
- ✅ GitHub Copilot
- ✅ Other skills-compatible AI agents
Skills are portable packages of procedural knowledge that work across any AI agent supporting the Agent Skills specification.
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
Installation
-
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 [email protected] JIRA_API_TOKEN=your-api-tokenFor Jira Server/DC with Personal Access Token:
JIRA_URL=https://jira.yourcompany.com JIRA_PERSONAL_TOKEN=your-personal-access-token -
Validate setup:
uv run scripts/core/jira-validate.py --verbose
Quick Start
# 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
Available Scripts
Core Operations (scripts/core/)
| Script | Commands | Usage |
|---|---|---|
jira-validate.py |
(default) | Validate environment setup |
jira-issue.py |
get, update | Get and update issues |
jira-search.py |
query | JQL search |
jira-worklog.py |
add, list | Time tracking |
Workflow Operations (scripts/workflow/)
| Script | Commands | Usage |
|---|---|---|
jira-create.py |
issue | Create new issues |
jira-transition.py |
list, do | Change issue status |
jira-comment.py |
add, list | Issue comments |
jira-sprint.py |
list, issues, current | Sprint operations |
jira-board.py |
list, issues | Board operations |
Utility Operations (scripts/utility/)
| Script | Commands | Usage |
|---|---|---|
jira-fields.py |
search, list | Find field IDs |
jira-user.py |
me, get | User information |
jira-link.py |
create, list-types | Issue linking |
Common Options
All scripts support:
--json- Output as JSON--quiet/-q- Minimal output--env-file PATH- Custom environment file--debug- Show detailed errors--help- Show command help
Write operations also support:
--dry-run- Preview changes without executing
Script Usage Examples
Search and Filter
# Find open bugs in project
uv run scripts/core/jira-search.py query "project = PROJ AND type = Bug AND status != Done"
# Find my assigned issues
uv run scripts/core/jira-search.py query "assignee = currentUser()"
# Output as JSON for processing
uv run scripts/core/jira-search.py query "project = PROJ" --json --max-results 100
Issue Management
# Get issue details
uv run scripts/core/jira-issue.py get PROJ-123
# Update issue fields (dry-run first)
uv run scripts/core/jira-issue.py update PROJ-123 --labels "urgent,backend" --dry-run
# Create new issue
uv run scripts/workflow/jira-create.py issue PROJ "Implement feature X" --type Story --priority Medium
Time Tracking
# Log time worked
uv run scripts/core/jira-worklog.py add PROJ-123 "2h 30m" -c "Implemented core logic"
# View worklogs
uv run scripts/core/jira-worklog.py list PROJ-123
Workflow Transitions
# List available transitions
uv run scripts/workflow/jira-transition.py list PROJ-123
# Transition issue (dry-run first)
uv run scripts/workflow/jira-transition.py do PROJ-123 "In Progress" --dry-run
# Execute transition
uv run scripts/workflow/jira-transition.py do PROJ-123 "In Progress"
Comments
# Add comment
uv run scripts/workflow/jira-comment.py add PROJ-123 "Investigation complete - root cause identified"
# List recent comments
uv run scripts/workflow/jira-comment.py list PROJ-123 --limit 5
Sprint & Board Operations
# List boards for project
uv run scripts/workflow/jira-board.py list --project PROJ
# Get board issues
uv run scripts/workflow/jira-board.py issues 42
# List sprints
uv run scripts/workflow/jira-sprint.py list 42 --state active
# Get sprint issues
uv run scripts/workflow/jira-sprint.py issues 123
# Get current sprint
uv run scripts/workflow/jira-sprint.py current 42
Utility Operations
# Search for custom fields
uv run scripts/utility/jira-fields.py search "story points"
# List all custom fields
uv run scripts/utility/jira-fields.py list --type custom
# Get current user info
uv run scripts/utility/jira-user.py me
# List available link types
uv run scripts/utility/jira-link.py list-types
# Create issue link
uv run scripts/utility/jira-link.py create PROJ-123 PROJ-456 --type "Blocks" --dry-run
Related Skills
- jira-syntax - Jira wiki markup validation and templates (unchanged)
Migration
Migrating from v2.x (MCP-based)? See Migration Guide.
Troubleshooting
"uv not found"
Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
"Environment file not found"
Create ~/.env.jira with your credentials.
"Authentication failed"
- Verify JIRA_URL is correct
- For Cloud: JIRA_USERNAME is your email
- For Server/DC: Use JIRA_PERSONAL_TOKEN instead
- Regenerate your API token if expired
Import errors when running scripts
Run scripts from the skill directory:
cd skills/jira-communication
uv run scripts/core/jira-issue.py get PROJ-123
License
MIT
Credits
Developed and maintained by Netresearch DTT GmbH.
Made with ❤️ for Open Source by Netresearch