Jira

Jira

Natural language interaction with Jira. Supports multiple backends.

Backend Detection

Run this check first to determine which backend to use:

1. Check if jira CLI is available:
   → Run: which jira
   → If found: USE CLI BACKEND

2. If no CLI, check for Atlassian MCP:
   → Look for mcp__atlassian__* tools
   → If available: USE MCP BACKEND

3. If neither available:
   → GUIDE USER TO SETUP

---

Quick Reference (CLI)

Skip this section if using MCP backend.

---

Quick Reference (MCP)

Skip this section if using CLI backend.

See references/mcp.md for full MCP patterns.

---

Triggers

• "create a jira ticket"
• "show me PROJ-123"
• "list my tickets"
• "move ticket to done"
• "what's in the current sprint"

---

Issue Key Detection

Issue keys follow the pattern: [A-Z]+-[0-9]+ (e.g., PROJ-123, ABC-1).

When a user mentions an issue key in conversation:

• CLI: jira issue view KEY or jira open KEY
• MCP: mcp__atlassian__jira_get_issue with the key

---

Workflow

Creating tickets: 1. Research context if user references code/tickets/PRs 2. Draft ticket content 3. Review with user 4. Create using appropriate backend

Updating tickets: 1. Fetch issue details first 2. Check status (careful with in-progress tickets) 3. Show current vs proposed changes 4. Get approval before updating 5. Add comment explaining changes

---

Before Any Operation

Ask yourself:

1. What's the current state? — Always fetch the issue first. Don't assume status, assignee, or fields are what user thinks they are.

2. Who else is affected? — Check watchers, linked issues, parent epics. A "simple edit" might notify 10 people.

3. Is this reversible? — Transitions may have one-way gates. Some workflows require intermediate states. Description edits have no undo.

4. Do I have the right identifiers? — Issue keys, transition IDs, account IDs. Display names don't work for assignment (MCP).

---

NEVER

• NEVER transition without fetching current status — Workflows may require intermediate states. "To Do" → "Done" might fail silently if "In Progress" is required first.

• NEVER assign using display name (MCP) — Only account IDs work. Always call lookupJiraAccountId first, or assignment silently fails.

• NEVER edit description without showing original — Jira has no undo. User must see what they're replacing.

• NEVER use `--no-input` without all required fields (CLI) — Fails silently with cryptic errors. Check project's required fields first.

• NEVER assume transition names are universal — "Done", "Closed", "Complete" vary by project. Always get available transitions first.

• NEVER bulk-modify without explicit approval — Each ticket change notifies watchers. 10 edits = 10 notification storms.

---

Safety

• Always show the command/tool call before running it
• Always get approval before modifying tickets
• Preserve original information when editing
• Verify updates after applying
• Always surface authentication issues clearly so the user can resolve them

---

No Backend Available

If neither CLI nor MCP is available, guide the user:

To use Jira, you need one of:

1. **jira CLI** (recommended):
   https://github.com/ankitpokhrel/jira-cli

   Install: brew install ankitpokhrel/jira-cli/jira-cli
   Setup:   jira init

2. **Atlassian MCP**:
   Configure in your MCP settings with Atlassian credentials.

---

Deep Dive

LOAD reference when:

• Creating issues with complex fields or multi-line content
• Building JQL queries beyond simple filters
• Troubleshooting errors or authentication issues
• Working with transitions, linking, or sprints

Do NOT load reference for:

• Simple view/list operations (Quick Reference above is sufficient)
• Basic status checks (jira issue view KEY)
• Opening issues in browser

References:

• CLI patterns: references/commands.md
• MCP patterns: references/mcp.md

Jira Skill

Natural language interaction with Jira for managing issues, sprints, and workflows. This skill enables Claude to view, create, update, and transition Jira tickets using conversational commands.

Purpose

The Jira skill bridges the gap between natural language requests and Jira operations. Instead of remembering specific CLI commands or API calls, you can simply tell Claude what you want to do with your Jira tickets, and the skill handles the technical details.

Key benefits:

• Conversational interface: Ask questions like "What are my open tickets?" or "Move PROJ-123 to Done"
• Dual backend support: Works with either the jira CLI or Atlassian MCP
• Safety-first approach: Always fetches current state before modifications and requires approval for changes
• Context-aware: Detects issue keys (e.g., PROJ-123) in conversation and offers relevant actions

When to Use

This skill activates when you:

• Mention Jira issue keys (e.g., "Show me PROJ-123", "What's the status of ABC-456?")
• Ask about tickets ("List my open tickets", "What's assigned to me?")
• Want to create issues ("Create a bug ticket for the login issue")
• Need to update tickets ("Move this to In Progress", "Assign PROJ-123 to me")
• Check sprint status ("What's in the current sprint?", "Show sprint backlog")
• Manage workflow ("Close this ticket", "Add a comment to PROJ-123")

Trigger phrases include:

• "create a jira ticket"
• "show me PROJ-123"
• "list my tickets"
• "move ticket to done"
• "what's in the current sprint"
• Any mention of "jira", "issue", "ticket", "sprint", or "backlog"

How It Works

1. Backend Detection

When activated, the skill first determines which backend is available:

1. CLI backend: Checks if the jira command is installed 2. MCP backend: Looks for Atlassian MCP tools (mcp__atlassian__*) 3. No backend: Guides you to install one of the above

2. Operation Execution

Once a backend is detected:

1. Read operations (viewing, listing): Execute immediately and display results 2. Write operations (create, update, transition):

• Fetch current issue state first
• Show proposed changes
• Request user approval
• Execute the operation
• Verify the result

3. Safety Checks

Before any modification, the skill:

• Fetches current issue state (never assumes status or assignee)
• Checks who else might be affected (watchers, linked issues)
• Verifies the operation is reversible or warns if not
• Confirms correct identifiers (transition IDs, account IDs)

Key Features

Issue Management

• View issues: See full details including description, status, assignee, and comments
• List issues: Filter by assignee, status, type, priority, labels, or custom JQL
• Create issues: Create tickets with full field support including multi-line descriptions
• Update issues: Modify summary, description, priority, labels, and custom fields
• Assign issues: Assign to yourself, others, or unassign

Workflow Operations

• Transition issues: Move tickets through workflow states (To Do, In Progress, Done)
• Add comments: Document progress or decisions on tickets
• Link issues: Create relationships between tickets (blocks, relates to, duplicates)

Sprint Management

• List sprints: View active, future, or closed sprints
• Sprint issues: See what's in the current sprint
• Add to sprint: Move issues into a sprint

Search and Query

• Natural language search: Find issues matching text queries
• JQL support: Use full Jira Query Language for complex searches
• Filter combinations: Combine assignee, status, type, and date filters

Usage Examples

Viewing Issues

"Show me PROJ-123"
"What's the status of ABC-456?"
"Display the details of that bug ticket"

Listing Issues

"List my open tickets"
"What issues are in progress?"
"Show me high priority bugs"
"Find all tickets updated this week"
"What's assigned to john@example.com?"

Creating Issues

"Create a bug ticket for the login timeout issue"
"Make a new task for updating the documentation"
"Create a story for implementing the export feature with acceptance criteria"

Updating Issues

"Move PROJ-123 to In Progress"
"Assign this ticket to me"
"Mark the bug as done"
"Add a comment saying the fix is deployed"
"Change the priority to high"

Sprint Operations

"What's in the current sprint?"
"Show me the active sprint"
"List sprint backlog items"

Advanced JQL Queries

"Find all bugs created this week"
"Show unassigned high-priority issues"
"List tickets I updated recently"
"Find issues blocked by PROJ-100"

Prerequisites

You need one of the following backends configured:

Option 1: jira CLI (Recommended)

The jira CLI provides fast, local access to Jira.

Installation:

# macOS
brew install ankitpokhrel/jira-cli/jira-cli

# Linux
# Download from https://github.com/ankitpokhrel/jira-cli/releases

Setup:

jira init

Follow the prompts to configure your Jira server URL and authentication.

Option 2: Atlassian MCP

The Atlassian MCP provides Jira access through Model Context Protocol.

Configure the Atlassian MCP in your Claude settings with your Atlassian credentials. This enables access to mcp__atlassian__* tools.

Output

Issue View

When viewing an issue, you'll see:

• Issue key and summary
• Status, priority, and type
• Assignee and reporter
• Description
• Recent comments
• Linked issues

Issue Lists

Lists display in a table format showing:

• Issue key
• Summary
• Status
• Assignee
• Priority

Operation Results

After modifications, the skill:

• Confirms the action was successful
• Shows the updated state
• Reports any errors with resolution guidance

Best Practices

Before Creating Issues

1. Check if a similar issue already exists 2. Understand the project's required fields 3. Use clear, descriptive summaries 4. Include acceptance criteria for stories

Before Transitioning

1. Let the skill fetch available transitions (they vary by project) 2. Some workflows require intermediate states 3. Add comments explaining why you're making the transition

For Assignments

1. With MCP, always use account IDs (not display names) 2. Verify the user exists in the project 3. Consider notifying the assignee separately

For Bulk Operations

1. Request explicit approval before bulk changes 2. Each change notifies watchers 3. Consider timing to avoid notification storms

General Tips

• Always let the skill fetch current state before modifications
• Preserve original information when editing descriptions
• Use the "open in browser" feature for complex editing
• Check linked issues before making major changes

Safety Guidelines

The skill follows strict safety protocols:

Always:

• Shows commands/tool calls before executing
• Requests approval before modifications
• Preserves original content when editing
• Verifies updates after applying
• Surfaces authentication issues clearly

Never:

• Transitions without fetching current status first
• Assigns using display names with MCP (only account IDs work)
• Edits descriptions without showing the original
• Uses --no-input without all required fields
• Assumes transition names are universal across projects
• Bulk-modifies without explicit approval

Troubleshooting

Authentication Issues

CLI:

# Reinitialize
jira init

# Verify connection
jira me

MCP:

• Check MCP connection status
• Reconnect the Atlassian service
• Verify API token permissions

Common Errors

Backend Not Available

If neither CLI nor MCP is available:

1. Install jira CLI (recommended):

   brew install ankitpokhrel/jira-cli/jira-cli
   jira init

2. Or configure Atlassian MCP in your Claude settings

Reference Files

For advanced usage, the skill includes detailed reference documentation:

• references/commands.md: Complete CLI command reference with examples
• references/mcp.md: Full MCP tool reference with JQL query guide

These are loaded on-demand when handling complex operations like:

• Multi-line descriptions
• Complex JQL queries
• Transition workflows
• Issue linking

Commands Reference

Complete reference for the jira CLI.

---

Viewing Issues

# View single issue
jira issue view ISSUE-KEY

# View with more comments
jira issue view ISSUE-KEY --comments 5

# Get raw JSON
jira issue view ISSUE-KEY --raw

---

Listing Issues

# List all issues in project
jira issue list

# List my issues
jira issue list -a$(jira me)

# Filter by status (use quotes for multi-word statuses)
jira issue list -s"In Progress"
jira issue list -s"To Do"
jira issue list -sDone

# Filter by type
jira issue list -tBug
jira issue list -tStory
jira issue list -tTask
jira issue list -tEpic

# Filter by priority
jira issue list -yHigh
jira issue list -yCritical

# Filter by label
jira issue list -lurgent -lbug

# Combine filters
jira issue list -a$(jira me) -s"In Progress" -yHigh

# Search with text
jira issue list "login error"

# Recently accessed
jira issue list --history

# Issues I'm watching
jira issue list -w

# Created/updated filters
jira issue list --created today
jira issue list --created week
jira issue list --updated -2d

# Plain output for scripting
jira issue list --plain --no-headers

# Specific columns
jira issue list --plain --columns key,summary,status,assignee

# Raw JQL query
jira issue list -q"status = 'In Progress' AND assignee = currentUser()"

# Paginate results
jira issue list --paginate 20
jira issue list --paginate 10:50 # start:limit

---

Creating Issues

# Interactive creation
jira issue create

# Non-interactive with all fields
jira issue create \
    -tBug \
    -s"Login button not working" \
    -b"Users cannot click the login button on Safari" \
    -yHigh \
    -lbug -lurgent

# Create and assign to self
jira issue create -tTask -s"Summary" -a$(jira me)

# Create subtask (requires parent)
jira issue create -tSub-task -P"PROJ-123" -s"Subtask summary"

# Create with custom fields
jira issue create -tStory -s"Summary" --custom story-points=3

# Skip prompts for optional fields
jira issue create -tTask -s"Quick task" --no-input

# Open in browser after creation
jira issue create -tBug -s"Bug title" --web

# Read description from file
jira issue create -tStory -s"Summary" --template /path/to/template.md

# Read description from stdin
echo "Description here" | jira issue create -tTask -s"Summary"

Multi-line content: The CLI chokes on multi-line strings. Write to /tmp first:

cat > /tmp/jira_body.md <<'EOF'
## Description
User needs ability to export data...

## Acceptance Criteria
- Export works for CSV
- Export works for JSON
EOF

jira issue create --no-input \
  -tStory \
  -pPROJ \
  -s"Add export functionality" \
  -b"$(cat /tmp/jira_body.md)"

---

Transitioning Issues

# Move to a state
jira issue move ISSUE-KEY "In Progress"
jira issue move ISSUE-KEY "Done"
jira issue move ISSUE-KEY "To Do"

# Move with comment
jira issue move ISSUE-KEY "Done" --comment "Completed the implementation"

# Move and set resolution
jira issue move ISSUE-KEY "Done" -R"Fixed"

# Move and reassign
jira issue move ISSUE-KEY "In Review" -a"reviewer@example.com"

# Open in browser after transition
jira issue move ISSUE-KEY "Done" --web

---

Assigning Issues

# Assign to specific user
jira issue assign ISSUE-KEY "user@example.com"
jira issue assign ISSUE-KEY "John Doe"

# Assign to self
jira issue assign ISSUE-KEY $(jira me)

# Assign to default assignee
jira issue assign ISSUE-KEY default

# Unassign
jira issue assign ISSUE-KEY x

---

Comments

# Add comment
jira issue comment add ISSUE-KEY -b"This is my comment"

# Add comment from file
jira issue comment add ISSUE-KEY --template /path/to/comment.md

---

Sprints

# List sprints
jira sprint list

# Active sprint only
jira sprint list --state active

# Add issue to sprint
jira sprint add SPRINT-ID ISSUE-KEY

# Close sprint
jira sprint close SPRINT-ID

---

Linking Issues

# Basic link
jira issue link PROJ-123 PROJ-456 "Relates"

# Blocker (blocker comes first)
jira issue link PROJ-100 PROJ-200 "Blocks"
# Meaning: PROJ-100 blocks PROJ-200

# Link to epic
jira issue link PROJ-EPIC PROJ-STORY "Epic-Story"

---

Other Commands

# Open issue in browser
jira open ISSUE-KEY

# Show current user
jira me

# Server info
jira serverinfo

# List projects
jira project list

# List boards
jira board list

MCP Reference

Complete reference for Atlassian Jira operations via MCP.

MCP Tool Reference

Search Operations

mcp__atlassian__searchJiraIssuesUsingJql

Search Jira using JQL (Jira Query Language).

Parameters:

• jql (required): JQL query string
• maxResults: Maximum results (default: 50)
• startAt: Pagination offset
• fields: Comma-separated fields to return

Example:

mcp__atlassian__searchJiraIssuesUsingJql(jql: "project = PROJ AND status = 'In Progress'")

Issue Operations

mcp__atlassian__getJiraIssue

Retrieve full issue details by key.

Parameters:

• issueKey (required): Issue key (e.g., "PROJ-123")
• expand: Additional data (changelog, transitions, renderedFields)

Example:

mcp__atlassian__getJiraIssue(issueKey: "PROJ-123")

mcp__atlassian__createJiraIssue

Create a new issue.

Parameters:

• projectKey (required): Target project
• issueType (required): Issue type (Story, Bug, Task, Epic, etc.)
• summary (required): Issue title
• description: Detailed description
• assignee: Account ID (use lookupJiraAccountId first)
• priority: Priority name (Highest, High, Medium, Low, Lowest)
• labels: Array of labels
• components: Array of component names
• Custom fields as needed

Example:

mcp__atlassian__createJiraIssue(
  projectKey: "PROJ",
  issueType: "Story",
  summary: "Implement user authentication",
  description: "Add OAuth2 authentication flow...",
  labels: ["backend", "security"]
)

mcp__atlassian__editJiraIssue

Update an existing issue.

Parameters:

• issueKey (required): Issue to update
• Any field to update (summary, description, assignee, etc.)

Example:

mcp__atlassian__editJiraIssue(
  issueKey: "PROJ-123",
  description: "Updated description with more details..."
)

Transition Operations

mcp__atlassian__getTransitionsForJiraIssue

Get available status transitions for an issue.

Parameters:

• issueKey (required): Issue key

Returns: List of available transitions with IDs and names.

mcp__atlassian__transitionJiraIssue

Change issue status.

Parameters:

• issueKey (required): Issue key
• transitionId (required): Transition ID from getTransitions
• comment: Optional comment for the transition

Workflow: 1. Get transitions: getTransitionsForJiraIssue("PROJ-123") 2. Find desired transition ID from results 3. Execute: transitionJiraIssue(issueKey: "PROJ-123", transitionId: "31")

Comment Operations

mcp__atlassian__addCommentToJiraIssue

Add a comment to an issue.

Parameters:

• issueKey (required): Issue key
• body (required): Comment text (supports Jira markdown)

User Operations

mcp__atlassian__lookupJiraAccountId

Find user account ID for assignments.

Parameters:

• query (required): Search by display name, email, or username

Example:

mcp__atlassian__lookupJiraAccountId(query: "user@example.com")

Usage: Always look up account IDs before assigning issues.

Project Operations

mcp__atlassian__getVisibleJiraProjects

List available Jira projects.

Parameters:

• maxResults: Maximum results

mcp__atlassian__getJiraProjectIssueTypesMetadata

Get issue types and required fields for a project.

Parameters:

• projectKey (required): Project key

Usage: Call before creating issues to understand required fields.

mcp__atlassian__getJiraIssueTypeMetaWithFields

Get detailed field metadata for an issue type.

Parameters:

• projectKey (required): Project key
• issueTypeId (required): Issue type ID

---

JQL (Jira Query Language) Reference

Basic Syntax

field operator value [AND|OR field operator value]

Common Fields

Operators

Functions

Relative Dates

# Days
created >= -7d    # Last 7 days
updated >= -30d   # Last 30 days

# Weeks
created >= -2w    # Last 2 weeks

# Months
created >= -1M    # Last month

# Specific date
created >= "2024-01-01"

Ordering

# Order by priority, highest first
project = PROJ ORDER BY priority DESC

# Multiple sort fields
project = PROJ ORDER BY status ASC, created DESC

Complex Query Examples

# My open issues, high priority
assignee = currentUser() AND status NOT IN (Done, Closed) AND priority >= High

# Bugs created this week
issuetype = Bug AND created >= startOfWeek() ORDER BY priority DESC

# Epics in progress with stories
issuetype = Epic AND status = "In Progress" AND issueFunction in hasLinks("is parent of")

# Issues updated by me recently
updatedBy = currentUser() AND updated >= -7d ORDER BY updated DESC

# Blocked issues
status = Blocked OR "Flagged" = "Impediment"

# Issues linked to specific epic
"Epic Link" = PROJ-100 AND status != Done

# Sprint backlog items
sprint in openSprints() AND status = "To Do" ORDER BY rank ASC

# Unassigned high-priority bugs
issuetype = Bug AND assignee IS EMPTY AND priority >= High

# Issues I'm watching
watcher = currentUser()

# Recently resolved by team
resolved >= -7d AND project = PROJ ORDER BY resolved DESC

---

Issue Linking

Limitation

The Atlassian MCP does not currently support creating issue links. Use the bundled jira-link-issues script instead.

Link Types

Script Usage

# Link PROJ-123 depends on PROJ-456
~/.claude/skills/jira/jira-link-issues PROJ-123 PROJ-456 "Depends On"

# PROJ-100 blocks PROJ-200
~/.claude/skills/jira/jira-link-issues PROJ-100 PROJ-200 "Blocks"

# General relationship
~/.claude/skills/jira/jira-link-issues PROJ-50 PROJ-75 "Relates To"

Finding Link Types

Query the Jira API to get available link types:

curl -s -u "$JIRA_USER:$JIRA_API_TOKEN" \
  "$JIRA_BASE_URL/rest/api/3/issueLinkType" | jq '.issueLinkTypes[].name'

Required environment variables:

• JIRA_BASE_URL: Your Atlassian instance (e.g., https://yourcompany.atlassian.net)
• JIRA_USER: Your email address
• JIRA_API_TOKEN: API token from Atlassian account settings

---

Description Formatting

Jira Markup (Wiki Style)

h1. Heading 1
h2. Heading 2
h3. Heading 3

*bold text*
_italic text_
-strikethrough-
+underline+

{code:java}
public class Example {
    // code here
}
{code}

{quote}
Quoted text here
{quote}

* Bullet list
** Nested bullet
# Numbered list
## Nested number

[Link text|https://example.com]
[Issue link|PROJ-123]

||Header 1||Header 2||
|Cell 1|Cell 2|

{panel:title=Panel Title}
Panel content here
{panel}

Atlassian Document Format (ADF)

For createJiraIssue, descriptions may use ADF format:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Description text"}
      ]
    }
  ]
}

---

Error Handling

Common Errors

Authentication Issues

If MCP tools return authentication errors: 1. Run /mcp to check connection status 2. Reconnect the Atlassian MCP service if disconnected 3. Verify API token permissions in Atlassian settings

Field Validation

Before creating issues: 1. Get project metadata: getJiraProjectIssueTypesMetadata 2. Check required fields for the issue type 3. Look up user account IDs for assignee fields 4. Verify custom field IDs and valid values

---

Common Workflows

Move Ticket to Done

1. Get available transitions:
   mcp__atlassian__getTransitionsForJiraIssue(issueKey: "PROJ-123")
   → Returns list with transition IDs

2. Find "Done" transition ID from response

3. Execute transition:
   mcp__atlassian__transitionJiraIssue(
     issueKey: "PROJ-123",
     transitionId: "done_id"
   )

4. Add comment:
   mcp__atlassian__addCommentToJiraIssue(
     issueKey: "PROJ-123",
     body: "Completed and deployed"
   )

Create and Assign Issue

1. Look up user account ID:
   mcp__atlassian__lookupJiraAccountId(query: "john@example.com")
   → Returns account ID

2. Create issue with assignment:
   mcp__atlassian__createJiraIssue(
     projectKey: "PROJ",
     issueType: "Task",
     summary: "Implement feature X",
     description: "Details here...",
     assignee: "account_id_from_step_1"
   )

List My In-Progress Issues

mcp__atlassian__searchJiraIssuesUsingJql(
  jql: "assignee = currentUser() AND status = 'In Progress' ORDER BY updated DESC"
)

Get Project Info Before Creating

1. List available projects:
   mcp__atlassian__getVisibleJiraProjects()

2. Get issue types for project:
   mcp__atlassian__getJiraProjectIssueTypesMetadata(projectKey: "PROJ")

3. Create issue with correct type:
   mcp__atlassian__createJiraIssue(
     projectKey: "PROJ",
     issueType: "Story",
     summary: "...",
     description: "..."
   )