Jira

Jira

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

Installation

1. Install Python dependencies:

``bash pip install --user requests keyring pyyaml ``

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

Setup Verification

After installation, verify the skill configuration by running:

$SKILL_DIR/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="you@example.com"
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: you@example.com
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

Configuration Defaults

Optionally configure defaults (JQL scope, fields, custom fields, project defaults) in ~/.config/agent-skills/jira.yaml. CLI arguments always override config defaults. See [configuration.md](references/configuration.md) for the full config format and defaults behavior.

# Show all configuration
$SKILL_DIR/scripts/jira.py config show

# Show project-specific defaults
$SKILL_DIR/scripts/jira.py config show --project DEMO

Commands

See [permissions.md](references/permissions.md) for read/write classification of each command.

check

Verify configuration and connectivity.

$SKILL_DIR/scripts/jira.py check

This validates:

• Python dependencies are installed
• Authentication is configured
• Can connect to Jira
• API version is detected and compatible

search

Search for issues using JQL (Jira Query Language).

$SKILL_DIR/scripts/jira.py search "project = DEMO AND status = Open"
$SKILL_DIR/scripts/jira.py search "assignee = currentUser() ORDER BY updated DESC" --max-results 20

Arguments:

• jql: JQL query string (required unless --contributor is used)
• --contributor: Search for issues where this user is a contributor (reporter, assignee, or commenter). On Jira Cloud, automatically resolves email/name to accountId.
• --project: Project key to scope a --contributor search
• --max-results: Maximum number of results (default: 50)
• --fields: Comma-separated list of fields to include

Deployment-specific queries:

The available JQL functions depend on your Jira deployment type. Run check to see your deployment type and ScriptRunner availability.

• All deployments: See [jql-reference.md](references/jql-reference.md)

for standard JQL patterns (status, dates, fields, ordering).

• Data Center/Server with ScriptRunner: See

[scriptrunner.md](references/scriptrunner.md) for advanced functions like linkedIssuesOf(), subtasksOf(), commentedByUser().

• Jira Cloud: ScriptRunner functions are not available. Use the

Cloud-native alternatives documented in [jql-reference.md](references/jql-reference.md#cloud-alternatives).

issue

Get, create, update, or comment on issues.

# Get issue details (--fields, --contributors)
$SKILL_DIR/scripts/jira.py issue get DEMO-123
$SKILL_DIR/scripts/jira.py issue get DEMO-123 --fields "summary,status,assignee" --contributors

# List comments
$SKILL_DIR/scripts/jira.py issue comments DEMO-123

# Create (--project, --type, --summary required; --description, --priority, --labels, --assignee, --set-field, --link, --from-file, --json)
$SKILL_DIR/scripts/jira.py issue create --project DEMO --type Task --summary "New task"
$SKILL_DIR/scripts/jira.py issue create --from-file issue.md --priority Critical

# Update (--summary, --description, --priority, --labels, --assignee, --set-field, --link, --from-file)
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --summary "Updated" --set-field story_points=5
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --link "Blocks:DEMO-456"

# Comment (--security-level for private comments)
$SKILL_DIR/scripts/jira.py issue comment DEMO-123 "This is a comment"

See [from-file-format.md](references/from-file-format.md) for the --from-file markdown format and [examples.md](references/examples.md) for more patterns.

transitions

Manage issue workflow transitions.

# List available transitions
$SKILL_DIR/scripts/jira.py transitions list DEMO-123

# Transition issue
$SKILL_DIR/scripts/jira.py transitions do DEMO-123 "In Progress"
$SKILL_DIR/scripts/jira.py transitions do DEMO-123 "Done" --comment "Completed"

# Transition with private comment
$SKILL_DIR/scripts/jira.py transitions do DEMO-123 "Done" --comment "Internal resolution notes" --security-level "Internal"

Additional Commands

See [advanced-commands.md](references/advanced-commands.md) for full documentation of these commands:

• config — view/manage configuration defaults and discover custom field mappings
• fields — list available fields (global or per project/issue type)
• statuses — list statuses and status categories
• user — search users by email/name (returns accountId on Cloud)
• collaboration — discover cross-team collaboration patterns in epics
• automations — list and inspect Jira automation rules (Cloud-only)

JQL Reference

Common JQL queries and patterns: see [jql-reference.md](references/jql-reference.md).

Quick reference — combine with AND, OR, and ORDER BY:

assignee = currentUser() AND statusCategory != Done ORDER BY priority DESC

Use statusCategory ("To Do", "In Progress", Done) for queries that work across projects.

Model Guidance

This skill makes API calls requiring structured input/output. A standard-capability model is recommended.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: odyssey4me
• Source: odyssey4me/agent-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.