| name | jira-reader |
| description | Read and analyze JIRA issues from Red Hat Issue Tracker. Use this skill to fetch issue details, search issues, extract comments and discussions, categorize issues (bugs, CVEs, features, stories), analyze custom fields (release notes, fix versions), retrieve Git links, traverse ticket graphs (parent, children, siblings, links), and generate summaries. This skill is read-only and cannot modify JIRA issues. Requires jira and ratelimit Python packages. |
| author | Gabriel McGoldrick (gmcgoldr@redhat.com) |
| allowed-tools | Read, Bash, Grep, Glob |
JIRA Reader Skill
This skill provides read-only access to JIRA issues on Red Hat Issue Tracker (https://redhat.atlassian.net). It uses the Atlassian REST API v3, which returns rich text fields (description, comments) in Atlassian Document Format (ADF). The skill automatically converts ADF to plain text.
Prerequisites
The script requires Python packages jira and ratelimit:
python3 -m pip install jira ratelimit
Capabilities
- Fetch Issue Details: Get full issue information including description, status, priority, assignee, components
- Process Comments: Extract and analyze comment threads with anonymized participants
- Extract Custom Fields: Access release note types, fix versions, and other custom fields
- Find Git Links: Retrieve related GitHub/GitLab pull requests and commits
- Categorize Issues: Classify issues as bugs, CVEs, features, stories, epics, tasks
- Generate Summaries: Create categorized reports and analysis of multiple issues
- Ticket Graph Traversal: Map relationships — parent, children, siblings, issue links, web links
Usage
The skill uses a Python script that connects to JIRA using an authentication token.
Environment Variables Required
Set in ~/.env (global) or .env in the project root (local override). See docs-skills README for setup:
JIRA_API_TOKEN=your-jira-api-token
JIRA_EMAIL=you@redhat.com
JIRA_URL=https://redhat.atlassian.net
The script loads .env files automatically — do not prepend source ~/.env to bash commands.
Examples
Fetch a single issue:
uv run --script ${CLAUDE_SKILL_DIR}/scripts/jira_reader.py --issue INFERENG-5233
Fetch issue with comments:
uv run --script ${CLAUDE_SKILL_DIR}/scripts/jira_reader.py --issue INFERENG-5233 --include-comments
Fetch multiple issues:
uv run --script ${CLAUDE_SKILL_DIR}/scripts/jira_reader.py --issue INFERENG-5233 --issue INFERENG-5049
Search issues by JQL (FAST - returns summaries):
uv run --script ${CLAUDE_SKILL_DIR}/scripts/jira_reader.py --jql "project=INFERENG AND status='In Progress'"
Search with full details (SLOW - fetches all fields):
uv run --script ${CLAUDE_SKILL_DIR}/scripts/jira_reader.py --jql "project=INFERENG AND status='In Progress'" --fetch-details
Traverse the ticket graph:
uv run --script ${CLAUDE_SKILL_DIR}/scripts/jira_reader.py --graph INFERENG-5233
Graph with custom limits:
uv run --script ${CLAUDE_SKILL_DIR}/scripts/jira_reader.py --graph INFERENG-5233 --max-children 10 --max-siblings 10 --max-links 20
Performance Modes
Default: Fast Summary Mode
JQL searches return summaries by default (1 API call, ~3 seconds for any number of results):
- issue_key, issue_type, issue_category, priority, status
- assignee, summary, fix_versions, url
Use for: Quick analysis, categorization, release planning, CVE reports
Opt-in: Detailed Mode (--fetch-details)
Fetches full details for each issue (N+1 API calls, ~2.5 seconds per issue):
- Everything in summary mode PLUS
- Full description, comments, git_links, created/updated dates, all custom fields
Use for: Deep analysis, comment threads, Git link extraction
Graph Mode (--graph)
Traverses ticket relationships:
- Ancestor chain — walks the parent chain (up to 2 levels by default) via standard parent field + Parent Link custom field. This means a task under an Epic under a Feature will return both the Epic and the Feature
- Children (via parent and Epic Link JQL queries, 1 level deep)
- Siblings (active statuses under same parent, 1 level deep)
- Issue links (blocks, clones, relates to)
- Remote/web links (classified as PRs, Google Docs, or other)
Use for: Understanding ticket context, documentation workflows, relationship mapping
Output Formats
Summary output (default for JQL):
{
"issue_key": "INFERENG-5233",
"issue_type": "Task",
"issue_category": "Task",
"priority": "Undefined",
"status": "New",
"assignee": null,
"summary": "Issue summary text",
"fix_versions": [],
"url": "https://redhat.atlassian.net/browse/INFERENG-5233"
}
Detailed output (with --fetch-details or --issue):
{
"issue_key": "INFERENG-5233",
"issue_type": "Task",
"issue_category": "Task",
"priority": "Undefined",
"status": "New",
"assignee": null,
"summary": "Issue summary text",
"description": "Full issue description...",
"created": "2026-03-16T08:34:09.302+0000",
"updated": "2026-03-16T09:03:46.166+0000",
"comments": [
{
"participant": "Participant A",
"timestamp": "2026-03-16 08:34",
"body": "Comment text..."
Graph output (with --graph):
{
"ticket": "INFERENG-5233",
"jira_url": "https://redhat.atlassian.net",
"parent": {"key": "INFERENG-5049", "summary": "...", "status": "New", "issuetype": "Epic"},
"ancestors": [
{"key": "INFERENG-5049", "summary": "...", "status": "New", "issuetype": "Epic", "priority": "Medium", "assignee": null, "description"
...
...
...
Rate Limiting
The skill respects JIRA API rate limits (2 calls per 5 seconds) to avoid overwhelming the server. Summary mode requires only 1 call regardless of result count, making it ~80x faster for bulk operations.
Security
- Read-only operations only (enforced by allowed-tools)
- Token stored in environment variable (not in code)
- Comment anonymization to protect user identities in analysis
Common Use Cases
- Analyze release issues: Fetch all issues for a fix version and categorize them
- CVE reporting: Extract security vulnerabilities and their status
- Bug triage: Get issue details with comments for understanding context
- Release notes: Extract information needed for documentation
- Link analysis: Find related Git changes for code review
- Ticket graph: Map relationships for documentation workflow context
