# jira-agent

> Interact with JIRA Cloud to fetch tickets, search using JQL, and list projects. Use when users ask about JIRA issues, tickets, projects, or need to query JIRA data. Requires JIRA_EMAIL, JIRA_API_TOKEN, and JIRA_DOMAIN environment variables.

- Author: Son Ngo
- Repository: imrimt/skills
- Version: 20251221155017
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/imrimt/skills
- Web: https://mule.run/skillshub/@@imrimt/skills~jira-agent:20251221155017

---

---
name: jira-agent
description: Interact with JIRA Cloud to fetch tickets, search using JQL, and list projects. Use when users ask about JIRA issues, tickets, projects, or need to query JIRA data. Requires JIRA_EMAIL, JIRA_API_TOKEN, and JIRA_DOMAIN environment variables.
allowed-tools: Bash, Read
---

# JIRA Agent Skill

Interact with JIRA Cloud to fetch ticket details, search issues using JQL queries, and list accessible projects.

## When to Use This Skill

Activate this skill when users ask questions like:
- "Show me JIRA ticket PROJ-123"
- "What's the status of ticket ABC-456?"
- "Search for all bugs assigned to me"
- "Find all open issues in the Marketing project"
- "List all projects I have access to"
- "What JIRA projects are available?"
- "Show me all high-priority tickets in Sprint 5"
- "What tickets are in progress?"

## Prerequisites

This skill requires three environment variables to be set:

- `JIRA_EMAIL`: Your Atlassian account email address
- `JIRA_API_TOKEN`: Your JIRA API token (create at: https://id.atlassian.com/manage-profile/security/api-tokens)
- `JIRA_DOMAIN`: Your JIRA Cloud domain (e.g., "yourcompany.atlassian.net")

IMPORTANT: On first use, the script will automatically discover your Cloud ID from your JIRA domain and cache it.

## How It Works

### Architecture
1. **Authentication**: Uses HTTP Basic Auth with email:API_TOKEN (Base64 encoded)
2. **Cloud ID Discovery**: Automatically discovers your cloudId from your JIRA domain
3. **API Endpoints**: Calls JIRA Cloud REST API v3 via `https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/...`
4. **Output Format**: Returns structured JSON that you parse and present to the user

### Operations

#### 1. Fetch Ticket Details
Retrieve complete information about a specific JIRA ticket by its key.

**Command**:
```bash
cd /Users/ngodu/.claude/skills/jira-agent
python3 scripts/jira.py fetch PROJ-123
```

**Returns**: JSON with ticket details including:
- Summary, description, status, priority
- Assignee, reporter, created/updated dates
- Labels, components, issue type

#### 2. Search with JQL
Search for issues using JIRA Query Language (JQL).

**Command**:
```bash
cd /Users/ngodu/.claude/skills/jira-agent
python3 scripts/jira.py search "project = PROJ AND status = 'In Progress'"
```

**JQL Examples**:
- `project = MARKETING AND assignee = currentUser()`
- `status IN ('To Do', 'In Progress') AND priority = High`
- `created >= -7d AND type = Bug`
- `sprint = 'Sprint 5' ORDER BY priority DESC`

**Returns**: JSON with array of matching issues (up to 50 by default, configurable with `--max-results`)

#### 3. List Projects
List all JIRA projects accessible to the authenticated user.

**Command**:
```bash
cd /Users/ngodu/.claude/skills/jira-agent
python3 scripts/jira.py list-projects
```

**Returns**: JSON array of projects with:
- Project key, name, description
- Project type (software, service_desk, etc.)
- Lead name

## Usage Instructions

### Step 1: Validate Environment
Before making any API calls, check that required environment variables are set:

```bash
cd /Users/ngodu/.claude/skills/jira-agent
python3 scripts/jira.py --check-env
```

If this fails, inform the user which environment variables are missing.

### Step 2: Execute Operation
Run the appropriate command based on the user's request:

```bash
# Fetch single ticket
python3 scripts/jira.py fetch TICKET-KEY

# Search with JQL
python3 scripts/jira.py search "JQL_QUERY" [--max-results N]

# List projects
python3 scripts/jira.py list-projects
```

### Step 3: Parse and Present Results
The script outputs structured JSON. Parse this JSON and present it in a user-friendly format:

**For fetch ticket**:
```
PROJ-123: Add user authentication
Status: In Progress
Priority: High
Assignee: John Doe
Reporter: Jane Smith
Created: 2024-12-01
Updated: 2024-12-15

Description:
[description text]

Labels: backend, security
Components: Authentication Module
```

**For search results**:
```
Found 5 issues matching your query:

1. PROJ-123: Add user authentication
   Status: In Progress | Priority: High | Assignee: John Doe

2. PROJ-124: Fix login bug
   Status: To Do | Priority: Critical | Assignee: Jane Smith
...
```

**For projects**:
```
Available JIRA Projects:

1. PROJ - Project Name (Software)
   Lead: John Doe

2. MARK - Marketing Project (Business)
   Lead: Jane Smith
...
```

### Step 4: Handle Errors Gracefully

Common errors and how to handle them:

- **Missing environment variables**: Tell user to set JIRA_EMAIL, JIRA_API_TOKEN, and JIRA_DOMAIN
- **Invalid API token**: Suggest regenerating token at https://id.atlassian.com/manage-profile/security/api-tokens
- **Ticket not found (404)**: Confirm ticket key is correct
- **Permission denied (403)**: User doesn't have access to this ticket/project
- **Invalid JQL (400)**: Explain the JQL syntax error to the user
- **Rate limit (429)**: Wait before making more requests

## Advanced Usage

### Filtering Search Results
Use JQL operators for precise queries:
- `assignee = currentUser()` - Issues assigned to you
- `created >= -7d` - Created in last 7 days
- `status CHANGED FROM "In Progress" TO "Done"` - Status changes
- `ORDER BY priority DESC, created DESC` - Sort results

### Pagination
For large result sets, use pagination:
```bash
python3 scripts/jira.py search "JQL" --max-results 50 --start-at 50
```

## Tips for Claude

- **Always validate environment first** using `--check-env` before making API calls
- **Parse JQL carefully**: JQL is case-sensitive for field values but not operators
- **Present summaries**: Don't dump raw JSON - format it nicely for the user
- **Handle ambiguity**: If user says "my tickets", translate to JQL: `assignee = currentUser()`
- **Error guidance**: If API returns error, explain what went wrong and suggest fixes
- **Combine operations**: Can fetch individual tickets after a search to get full details

## Dependencies

- Python 3.7+
- `requests` library (for HTTP calls)

Install with:
```bash
pip install requests
```

## Notes

- All timestamps are in ISO 8601 format (UTC)
- The script caches cloudId discovery to avoid repeated calls
- API token is sensitive - never log it or display it
- Rate limits apply - be mindful of excessive API calls
- JQL must be URL-encoded when sent via GET (script handles this automatically)