---

name: using-jira-tool description: Use when user provides Jira issue URLs or mentions Jira tickets - fetches issue details and comments from Jira Cloud using local jira tool, outputs AI-optimized markdown for context gathering

Using the Jira Tool

Overview

Core principle: When users mention Jira issues or provide Jira URLs, immediately run jira <url-or-key>. Don't explore code, don't explain internals, just use the tool.

The jira tool is a Python CLI that fetches Jira Cloud issues (description, comments, metadata) and outputs AI-optimized markdown to stdout.

IMMEDIATE ACTION REQUIRED:

1. Check tool exists: which jira
2. Run tool: jira "<url or key>"
3. Display output

That's it. No analysis, no explanation, no code reading.

When to Use

Use jira tool when:

• User provides Jira URL: https://*.atlassian.net/browse/KEY-123
• User mentions issue key: "check PLATFORM-5678"
• User asks for issue context: "what does SP-1234 say?"
• User asks to implement from a Jira ticket

Don't use when:

• Jira URLs are just reference links (not requesting data)
• User wants to CREATE Jira issues (tool is read-only)

Quick Reference

Prerequisites Check

Before using the tool, verify:

Copy# 1. Tool exists
which jira

# 2. Dependencies installed
python -m pip list | grep -E "requests|python-dotenv"

# 3. Configuration exists
ls .env

If missing:

• .env not found → Tell user to create it with ATLASSIAN_EMAIL, ATLASSIAN_TOKEN, ATLASSIAN_DOMAIN
• Dependencies missing → Run pip install -r requirements.txt
• Tool not found → Not a jira-enabled repository

Usage Pattern

Basic Flow

Copy# Direct issue key
jira SP-1234

# Full URL (with or without query params)
jira "https://company.atlassian.net/browse/TICKET-123"
jira "https://company.atlassian.net/browse/TICKET-123?filter=all"

Integration Workflows

Gather context before implementation:

Copy# Fetch requirements
jira "https://company.atlassian.net/browse/FEATURE-456" > requirements.md

# Read and implement
cat requirements.md
# [implement based on requirements]

Read issue during debugging:

Copy# Fetch bug report
jira BUG-789

# Use output to understand the issue
# [debug based on description and comments]

Output Format

The tool outputs markdown with:

• Metadata: Issue key, status, priority, assignee, reporter, labels, timestamps
• Description: Original issue description (Jira markup → Markdown)
• Comments: All comments with author and timestamp

Structure:

Copy# [KEY-123] Issue Title

**Issue Key:** KEY-123
**Status:** In Progress
**Priority:** High
...

---

## Original Description

[Description content in markdown]

---

## Comments (N total)

### Comment by Author on YYYY-MM-DD HH:MM UTC
[Comment content]

Error Handling

All errors go to stderr - stdout remains clean for piping.

Common Mistakes

❌ Exploring code instead of using tool

Copy# DON'T: Spend time reading jira.py source
Read jira to understand API calls...

# DO: Just use it
jira PROJ-123

❌ Using WebFetch for Jira URLs

Copy# DON'T: Fetch HTML page
WebFetch https://company.atlassian.net/browse/PROJ-123

# DO: Use jira tool for structured data
jira PROJ-123

❌ Forgetting to quote URLs

Copy# DON'T: Breaks on query params
jira https://site.atlassian.net/browse/KEY-123?filter=all

# DO: Quote URLs
jira "https://site.atlassian.net/browse/KEY-123?filter=all"

❌ Not checking prerequisites

Copy# DON'T: Run without checking
jira PROJ-123
# FileNotFoundError: .env

# DO: Verify setup first
ls .env && jira PROJ-123

❌ Using absolute paths

Copy# DON'T: Use absolute path
/Users/matteo.barbieri/dev/matteo/toolbox/jira_client/jira PROJ-123

# DO: Use python command with relative path
jira PROJ-123

Recognition Workflow

When user mentions Jira:

1. Look for jira in path: which jira
2. If found → Use the tool directly (see Quick Reference table)
3. If not found → Tell user the jira command is not available

Red Flags - STOP and Use Tool

If you catch yourself doing ANY of these, STOP immediately:

• Reading jira.py source code
• Mentioning function names like extract_issue_key() or format_issue_markdown()
• Explaining how the tool works internally
• Analyzing the API implementation
• "Let me understand the codebase first"
• "I'll explore how this works"

All of these mean: Just run jira <issue> and move on.

Rationalization Table

Real-World Impact

Without skill:

• Agents explore jira.py source code (wasting time)
• Use WebFetch to scrape HTML (loses structure)
• Don't discover tool exists

With skill:

• Immediate tool discovery: jira KEY-123
• Structured markdown output ready for AI consumption
• Clear error messages guide prerequisite setup