Jira Integration Skill

Purpose: Issue management for Jira Cloud using the jira CLI with JSON output optimized for LLM agents.

Tool: jira CLI (installed globally via npm link from ~/utils/atlassian)

•Prerequisites
•Decision Tree
•Quick Command Reference
•Pattern Recognition - Auto-Invocation
•Workflow Examples
•Error Handling
•JSON Output Handling
•Comparison: Quick Read vs Fetch
•Version History

Prerequisites

Verify Installation

bash

# Check CLI installed
jira --version  # Expects: 1.0.0

Authentication

Config location: ~/utils/atlassian/.env

env

ATLASSIAN_CLOUD_ID=your-cloud-id
ATLASSIAN_AUTH_TOKEN=email@domain.com:API_TOKEN
ATLASSIAN_SITE_URL=https://your-site.atlassian.net

Get API token from: https://id.atlassian.com/manage-profile/security/api-tokens

Decision Tree

Issue Operations

code

User wants to...
├── View issue details
│   └── jira issues read <ISSUE-KEY>
├── List recent issues
│   └── jira issues list [--limit N] [--project KEY]
├── Search issues
│   └── jira issues search "query" [--project KEY]
├── Create new issue
│   └── jira issues create "Title" --project KEY [options]
├── Update existing issue
│   └── jira issues update <ISSUE-KEY> [--status|--assignee|--priority]
├── Fetch complete hierarchy
│   └── jira issues fetch <ISSUE-KEY> --output ./spec
└── Get available transitions
    └── jira issues transitions <ISSUE-KEY>

Metadata Operations

code

User wants to...
├── List projects
│   └── jira projects list
└── List users
    └── jira users list [--query NAME]

Comments

code

├── Add comment
│   └── jira comments create <ISSUE-KEY> --body "Comment text"
└── List comments
    └── jira comments list <ISSUE-KEY>

Quick Command Reference

Issues CRUD

Operation	Command	Example
Read	`jira issues read <KEY>`	`jira issues read VA-2228`
List	`jira issues list`	`jira issues list --limit 10 --project VA`
Search	`jira issues search "query"`	`jira issues search "auth bug"`
Create	`jira issues create "Title"`	`jira issues create "Fix login" --project VA --type Bug`
Update	`jira issues update <KEY>`	`jira issues update VA-123 --status "In Review"`
Fetch	`jira issues fetch <KEY>`	`jira issues fetch VA-123 --output ./spec`

Create Issue Options

bash

jira issues create "Title" \
  --project VA \
  --type Story \
  --description "Detailed description" \
  --assignee "account-id" \
  --priority High \
  --labels "Bug,Critical" \
  --parent VA-100

Issue types: Epic, Story, Task, Bug, Sub-task Priority values: Highest, High, Medium, Low, Lowest

Update Issue Options

bash

jira issues update VA-123 \
  --status "In Review" \
  --assignee "account-id" \
  --priority High \
  --labels "Bug,P1" \
  --summary "New title"

Fetch (Comprehensive Hierarchy)

bash

# Fetch epic with ALL children + linked Confluence pages
jira issues fetch VA-2522 --output ./spec

# Output structure:
# ./spec/
# ├── jira/
# │   ├── VA-2522.json
# │   ├── VA-2522.md
# │   ├── VA-2228.json  (child)
# │   └── ...
# ├── confluence/
# │   ├── 12345678.json
# │   └── ...
# └── summary.json

When to use fetch:

•Implementing a feature from Jira epic/story
•Need complete requirements with all children
•Building offline reference materials
•Want all linked Confluence pages automatically

Metadata Queries

bash

# Projects
jira projects list

# Users
jira users list
jira users list --query "john"

Comments

bash

# Add comment
jira comments create VA-123 --body "This is a comment"

# List comments
jira comments list VA-123

Pattern Recognition - Auto-Invocation

High Confidence Triggers (invoke immediately)

yaml

Issue Operations:
  - "Create a Jira issue for..."
  - "Open a ticket in Jira..."
  - "Log this as a Jira bug..."
  - "Check Jira issue VA-123"
  - "What's the status of VA-123?"
  - "Update VA-123 to..."
  - "Move VA-123 to In Review"
  - "Assign VA-123 to..."
  - "Search Jira for..."
  - "Find issues about..."

Fetch Operations (comprehensive):
  - "Fetch VA-2228"
  - "Pull down VA-2522"
  - "Get complete data for VA-2228"
  - "Implement from VA-2228"
  - "Get requirements for VA-2228"

Metadata:
  - "List Jira projects"
  - "Who can I assign this to?"

Issue ID Detection

regex

# Jira issue ID pattern
[A-Z]{2,10}-\d+

# Examples: VA-123, DEV-456, BACKEND-789

Workflow Examples

Create Issue from Bug Report

yaml

User: "Create a Jira issue for the login timeout bug"

Steps:
  1. Parse request: title=login timeout bug
  2. Execute: jira issues create "Login timeout bug" --project VA --type Bug
  3. Return: Issue key and details from JSON

Check Issue Status

yaml

User: "What's the status of VA-123?"

Steps:
  1. Parse issue ID: VA-123
  2. Execute: jira issues read VA-123
  3. Return: Issue title, state, assignee, priority from JSON

Update Issue State

yaml

User: "Move VA-123 to In Review and assign to John"

Steps:
  1. Get users: jira users list --query john
  2. Find John's account ID from JSON
  3. Update: jira issues update VA-123 --status "In Review" --assignee john-account-id

Implement from Jira Epic

yaml

User: "Implement VA-2522"

Steps:
  1. Check if reference exists: ls ./spec/jira/VA-2522.json
  2. If not: jira issues fetch VA-2522 --output ./spec
  3. Read requirements from ./spec/jira/*.md
  4. Begin implementation
  5. Update progress: jira issues update VA-2228 --status "In Progress"

Error Handling

Error	Cause	Resolution
`command not found: jira`	CLI not installed	`cd ~/utils/atlassian && npm link`
`Missing ATLASSIAN_AUTH_TOKEN`	No credentials	Configure `~/utils/atlassian/.env`
`Authentication failed`	Invalid token	Regenerate API token
`Resource not found`	Invalid issue key	Verify issue exists
`Status not available`	Invalid transition	Run `jira issues transitions VA-123` to see options
`Rate limited`	Too many requests	CLI auto-retries with backoff

JSON Output Handling

All commands output JSON. Parse with jq:

bash

# Get issue title
jira issues read VA-123 | jq -r '.summary'

# Get issue status
jira issues read VA-123 | jq -r '.status'

# List issue keys and titles
jira issues list --limit 10 | jq -r '.[] | "\(.key): \(.summary)"'

# Get created issue key
jira issues create "Title" --project VA | jq -r '.key'

Comparison: Quick Read vs Fetch

Need	Use `read`	Use `fetch`
Quick status check	Yes	No
Get single issue	Yes	Overkill
Get issue + ALL children	No	Yes
Get linked Confluence	No	Yes (automatic)
Offline reference	No	Yes
Implementation context	No	Yes
Real-time current data	Yes	Snapshot

Version History

•
v1.0 (2025-12-29): CLI-first architecture replacing MCP-based approach
- •Full CRUD operations via jira CLI
- •Comprehensive fetch with hierarchy traversal
- •JSON output for LLM parsing
- •Mirrors Linear skill pattern

managing-jira-issues

Jira Integration Skill

Table of Contents

Prerequisites

Verify Installation

Authentication

Decision Tree

Issue Operations

Metadata Operations

Comments

Quick Command Reference

Issues CRUD

Create Issue Options

Update Issue Options

Fetch (Comprehensive Hierarchy)

Metadata Queries

Comments

Pattern Recognition - Auto-Invocation

High Confidence Triggers (invoke immediately)

Issue ID Detection

Workflow Examples

Create Issue from Bug Report

Check Issue Status

Update Issue State

Implement from Jira Epic

Error Handling

JSON Output Handling

Comparison: Quick Read vs Fetch

Version History