name: jira
description: Search and manage Jira issues using JQL queries, create/update issues, and manage workflows. Use when working with Jira project management.
metadata:
author: odyssey4me
version: "0.2.0"
license: MIT

Jira

Interact with Jira for issue tracking, search, and workflow management.

Installation

1. Install Python dependencies:
   bash pip install --user requests keyring pyyaml

2. Download the skill from Releases or use directly from this repository.

Setup Verification

After installation, verify the skill is properly configured:

python scripts/jira.py check

This will check:
- Python dependencies (requests, keyring, pyyaml)
- Authentication configuration
- Connectivity to Jira

If anything is missing, the check command will provide setup instructions.

Authentication

Configure Jira authentication using one of these methods:

Option 1: Environment Variables (Recommended)

export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="your-token"

Add these to your ~/.bashrc or ~/.zshrc for persistence.

Option 2: Config File

Create ~/.config/agent-skills/jira.yaml:

url: https://yourcompany.atlassian.net
email: [email protected]
token: your-token

Required Credentials

• URL: Your Jira instance URL (e.g., https://yourcompany.atlassian.net)
• Email: Your Atlassian account email
• API Token: Create at https://id.atlassian.com/manage-profile/security/api-tokens

Rate Limits

Atlassian Jira Cloud enforces rate limits to ensure fair usage and system stability. The specific limits vary based on your Jira instance type and plan:

• Jira Cloud: Rate limits vary by endpoint and are enforced per-user and per-app
• Jira Data Center/Server: Rate limits are typically configured by administrators

Automatic Rate Limit Handling

This skill automatically handles temporary rate limit errors (429 Too Many Requests) by:
- Detecting rate limit responses from the Jira API
- Waiting for the time specified in the Retry-After header
- Retrying failed requests up to 3 times with exponential backoff (1s, 2s, 4s)
- Providing clear error messages if rate limits persist after all retry attempts

You don't need to manually handle rate limiting - the skill manages this automatically. If you encounter persistent rate limit errors, consider:
- Reducing the frequency of API calls
- Using --max-results to limit the number of items returned
- Spreading bulk operations over a longer time period
- Contacting your Jira administrator if limits seem too restrictive

Best Practices for AI Agents

When using this skill for bulk operations or automated workflows:
1. Use specific JQL queries to minimize the number of API calls needed
2. Leverage configuration defaults and JQL scope to avoid redundant filters
3. Use --max-results appropriately - don't fetch more data than needed
4. For large datasets, consider paginating manually with multiple smaller queries
5. Be aware that search operations may be more heavily rate-limited than direct issue access

Configuration Defaults

Optionally configure defaults in ~/.config/agent-skills/jira.yaml to reduce repetitive typing:

# Authentication (optional if using environment variables)
url: https://yourcompany.atlassian.net
email: [email protected]
token: your-token

# Optional defaults
defaults:
  jql_scope: "project = DEMO AND assignee = currentUser()"
  security_level: "Red Hat Internal"
  max_results: 25
  fields: ["summary", "status", "assignee", "priority", "created"]

# Optional project-specific defaults
projects:
  DEMO:
    issue_type: "Task"
    priority: "Medium"
  PROD:
    issue_type: "Bug"
    priority: "High"

How Defaults Work

• CLI arguments always override config defaults
• JQL scope is prepended to all searches: (scope) AND (your_query)
• Security level applies to comments and transitions with comments
• Project defaults apply when creating issues in that project

View Configuration

# Show all configuration
python scripts/jira.pyconfig show

# Show project-specific defaults
python scripts/jira.pyconfig show --project DEMO

Commands

check

Verify configuration and connectivity.

python scripts/jira.py check

This validates:
- Python dependencies are installed
- Authentication is configured
- Can connect to Jira
- API version is detected correctly

search

Search for issues using JQL (Jira Query Language).

# Standard JQL
python scripts/jira.pysearch "project = DEMO AND status = Open"
python scripts/jira.pysearch "assignee = currentUser() ORDER BY updated DESC" --max-results 20

# ScriptRunner Enhanced Search (if available)
# Find issues linked to a specific issue
python scripts/jira.pysearch 'issue in linkedIssuesOf("DEMO-123")'

# Find parent/child relationships
python scripts/jira.pysearch 'issue in parentsOf("DEMO-123")'
python scripts/jira.pysearch 'issue in subtasksOf("DEMO-123")'

# Find issues commented on by a specific user
python scripts/jira.pysearch 'issue in commentedByUser("username")'

# Find epics and their issues
python scripts/jira.pysearch 'issue in epicsOf("DEMO-123")'
python scripts/jira.pysearch 'issue in issuesInEpics("EPIC-123")'

# Find issues with specific link types (dependencies, blocks, etc.)
python scripts/jira.pysearch 'issue in hasLinkType("Dependency")'

Arguments:
- jql: JQL query string (required) - supports ScriptRunner functions if installed
- --max-results: Maximum number of results (default: 50)
- --fields: Comma-separated list of fields to include
- --json: Output as JSON

ScriptRunner Support:

The skill automatically detects if ScriptRunner Enhanced Search is installed and validates queries that use advanced JQL functions. If ScriptRunner functions are detected but the plugin is not available, you'll receive a warning.

Common ScriptRunner functions include:
- linkedIssuesOf(), hasLinkType() - Link and dependency queries
- subtasksOf(), parentsOf(), epicsOf() - Hierarchy navigation
- commentedByUser(), transitionedBy() - User activity tracking
- And many more...

For complete ScriptRunner guidance including user lookups, practical examples, and troubleshooting, read scriptrunner.md.

Note: ScriptRunner works differently on Cloud vs Data Center/Server instances. The skill handles both automatically.

issue

Get, create, update, or comment on issues.

# Get issue details
python scripts/jira.pyissue get DEMO-123

# Create new issue
python scripts/jira.pyissue create --project DEMO --type Task --summary "New task"

# Update issue
python scripts/jira.pyissue update DEMO-123 --summary "Updated summary"

# Add comment
python scripts/jira.pyissue comment DEMO-123 "This is a comment"

# Add private comment with security level
python scripts/jira.pyissue comment DEMO-123 "Internal note" --security-level "Red Hat Internal"

transitions

Manage issue workflow transitions.

# List available transitions
python scripts/jira.pytransitions list DEMO-123

# Transition issue
python scripts/jira.pytransitions do DEMO-123 "In Progress"
python scripts/jira.pytransitions do DEMO-123 "Done" --comment "Completed"

# Transition with private comment
python scripts/jira.pytransitions do DEMO-123 "Done" --comment "Internal resolution notes" --security-level "Red Hat Internal"

config

Manage configuration and view effective defaults.

# Show all configuration and defaults
python scripts/jira.pyconfig show

# Show project-specific defaults
python scripts/jira.pyconfig show --project DEMO

This displays:
- Authentication settings (with masked token)
- Default JQL scope, security level, max results, and fields
- Project-specific defaults for issue type and priority

Examples

Verify Setup

python scripts/jira.py check

Find my open issues

python scripts/jira.pysearch "assignee = currentUser() AND status != Done ORDER BY priority DESC"

Create a bug report

python scripts/jira.pyissue create \
  --project DEMO \
  --type Bug \
  --summary "Login button not working" \
  --description "The login button on the homepage does not respond to clicks."

Move issue through workflow

# Start work on an issue
python scripts/jira.pytransitions do DEMO-123 "In Progress"

# Complete the issue
python scripts/jira.pytransitions do DEMO-123 "Done" --comment "Implemented and tested"

Add private comment

# Add comment visible only to specific security level
python scripts/jira.pyissue comment DEMO-123 \
  "This is sensitive internal information" \
  --security-level "Red Hat Internal"

Search with specific fields

python scripts/jira.pysearch \
  "project = DEMO AND created >= -7d" \
  --fields "key,summary,status,assignee,created"

Using Configuration Defaults

With defaults configured as shown in the Configuration Defaults section:

# Search uses JQL scope automatically
python scripts/jira.pysearch "status = Open"
# Becomes: (project = DEMO AND assignee = currentUser()) AND (status = Open)

# Search with automatic max_results and fields from config
python scripts/jira.pysearch "priority = High"
# Uses configured max_results (25) and fields automatically

# Create issue uses project defaults
python scripts/jira.pyissue create --project DEMO --summary "Fix login bug"
# Automatically uses issue_type="Task" and priority="Medium" from DEMO project defaults

# Comments use default security level
python scripts/jira.pyissue comment DEMO-123 "Internal note"
# Automatically applies security_level="Red Hat Internal"

# Override defaults when needed
python scripts/jira.pysearch "status = Open" --max-results 100
# CLI argument overrides the configured default of 25

JQL Reference

Common JQL queries:

Combine with AND, OR, and use ORDER BY for sorting.

Troubleshooting

Check command fails

Run python scripts/jira.pycheck to diagnose issues. It will provide specific error messages and setup instructions.

Authentication failed

1. Verify your API token is correct
2. Ensure you're using your email (not username)
3. For Jira Cloud, use your Atlassian account email
4. For Jira Data Center/Server, use your username

Permission denied

You may not have access to the requested project or issue. Contact your Jira administrator.

JQL syntax error

Use the Jira web interface to test your JQL query before using it in scripts.

Import errors

Ensure dependencies are installed:

pip install --user requests keyring pyyaml