name: jira-builders description: | Guides for using jira-tool CLI correctly to create and manages Jira tickets with rich formatting. Use when working with Jira tickets, epics, or exports. Triggers on "create Jira ticket", "search Jira", "get Jira ticket", "export Jira data", "list epics", or any Jira API operations. Prevents common mistakes like trying to import jira_tool Python module or using curl unnecessarily. Works with jira-tool CLI command and environment variables (JIRA_BASE_URL, JIRA_USERNAME, JIRA_API_TOKEN).

Jira Ticket Management

Use jira-tool CLI for all Jira operations.

Core Commands

# Get ticket
jira-tool get WPCW-370

# Search
jira-tool search 'project=WPCW AND status="To Do"'

# List epics
jira-tool epics --project WPCW

# Create epic
jira-tool create --project WPCW --type Epic --summary "Title"

# Create story under epic
jira-tool create --project WPCW --type Story --summary "Title" --parent WPCW-370

# Create subtask
jira-tool create --project WPCW --type Sub-task --summary "Title" --parent WPCW-371

# Export for analysis
jira-tool export --project WPCW --all --format jsonl -o data.jsonl

Rich Descriptions

Use heredoc for multi-line descriptions:

jira-tool create --project WPCW --type Epic \
  --summary "User Authentication" \
  --description "$(cat <<'EOF'
Implement OAuth2 authentication with session management.

**Problem Statement:**
Users cannot securely log in.

**Acceptance Criteria:**
- User can log in with email/password
- Session persists across refresh
- Logout invalidates sessions
EOF
)"

Batch Operations

Shell scripts with jira-tool:

#!/bin/bash
EPIC=$(jira-tool create --project WPCW --type Epic \
  --summary "Parent Epic" --format json | jq -r '.key')

for task in "Task 1" "Task 2" "Task 3"; do
  jira-tool create --project WPCW --type Story \
    --summary "$task" --parent "$EPIC"
done

Data Processing

Export and process with shell tools:

# Export tickets
jira-tool export --project WPCW --all --format jsonl -o tickets.jsonl

# Process with jq
jq -r 'select(.fields.status.name == "To Do") | .key' tickets.jsonl

When to Use What

• Single operation: jira-tool directly
• Batch operations: Shell scripts with jira-tool in loops
• Complex workflows: Invoke jira-ticket-manager agent
• Data analysis: Export + process with jq/awk

Requirements

• jira-tool CLI installed (check with jira-tool --version)
• Environment: JIRA_BASE_URL, JIRA_USERNAME, JIRA_API_TOKEN

Critical Anti-Patterns to Avoid

DO NOT:

1. Import jira_tool Python module - it's internal/private

   # WRONG - This will fail
   from jira_tool import JiraClient
   

2. Use curl for Jira API unless jira-tool doesn't support the operation

   # WRONG - Fragile, error-prone
   curl -u "$JIRA_USERNAME:$JIRA_API_TOKEN" "$JIRA_BASE_URL/rest/api/3/search"
   

3. Create multiple scripts for same purpose (violates DRY principle)

   # WRONG - Multiple scripts for slight variations
   pull_tickets_basic.py, pull_tickets_filtered.py, pull_tickets_csv.py
   

DO:

1. Use jira-tool CLI for all operations

   # RIGHT - Use the CLI
   jira-tool search 'project=WPCW'
   

2. Use subprocess if you need programmatic access

   # RIGHT - Call CLI from Python
   import subprocess
   result = subprocess.run(['jira-tool', 'get', 'PROJ-123'],
                          capture_output=True, text=True)
   

3. Use command-line flags for variations

   # RIGHT - One script with options
   jira-tool export --format csv --filter status=Open -o file.csv
   

Supporting References

• Quick Reference: ~/.claude/skills/jira-builders/references/QUICK_REFERENCE.md - Common CLI patterns and examples
• Tool Selection: ~/.claude/skills/jira-builders/references/TOOL_SELECTION.md - When to use CLI vs agent vs curl