jira

Jira Skill

View Jira issues, generate branch names from tickets, transition issue status — all via Atlassian MCP.

Trigger

• Keywords: jira, ticket, issue key ([A-Z][A-Z0-9]+-\d+), branch from ticket, transition status, start work, pr opened, pr merged
• User says /jira

When NOT to Use

• GitHub Issues → use /issue-analyze
• Searching Jira issues → v1.1 (deferred)
• Generic project management

Input Parsing

Extract issueKey and optional host from user input:

Input Format	Example	Extraction
Bare key	OK-51513	key=OK-51513
Full URL	https://foo.atlassian.net/browse/OK-51513	key=OK-51513, host=foo.atlassian.net
Software URL	https://foo.atlassian.net/jira/software/.../OK-51513	key=OK-51513, host=foo.atlassian.net
Branch context	(auto from git branch --show-current)	key via {TICKET_PATTERN} regex

Regex:

• Issue key: ([A-Z][A-Z0-9]+-\d+)
• Host: https?://([^/]+\.atlassian\.net)

CloudId Resolution

1. Call getAccessibleAtlassianResources()
2. 0 results → error: "Atlassian MCP not configured or unauthorized"
3. 1 result  → use its cloudId automatically
4. N results →
     Host provided and matches?    → use matching cloudId
     Host provided but no match?   → warn: "Host '<host>' not found. Available: ..." → AskUserQuestion to select or abort
     No host?                      → AskUserQuestion to choose instance

Do NOT persist cloudId. Resolve at runtime each time; Claude context naturally caches within a session.

Subcommand: view

Step	Action
1	Parse input → issueKey (+ host if URL)
2	Resolve cloudId
3	getJiraIssue(cloudId, issueKey)
4	Format output

Output format:

## KEY: Summary

| Field | Value |
|-------|-------|
| Status | ... |
| Assignee | ... |
| Priority | ... |
| Type | ... |
| Created | ... |

### Description
(first 500 chars, truncated if longer)

Subcommand: branch

Step	Action
1	Parse input → issueKey
2	Resolve cloudId
3	getJiraIssue → get summary + issuetype
4	Map issue type → branch prefix (see references/branch-policy.md)
5	Apply --type override if provided
6	Generate slug from summary
7	Assemble branch name: ${prefix}/${issueKey}-${slug}
8	Check collision (local + remote)
9	Plan mode: output branch name + command. Execute mode: run git checkout -b

See references/branch-policy.md for full mapping table, slug algorithm, and collision detection.

Plan output (default):

Branch: feat/OK-51513-add-user-profile-page
From: OK-51513 "Add user profile page" (Story)

To create: git checkout -b feat/OK-51513-add-user-profile-page

Execute mode (--execute): run git checkout -b <branch> directly.

Subcommand: transition

Step	Action
1	Parse input → issueKey + --event value
2	Resolve cloudId
3	getJiraIssue → current status
4	getTransitionsForJiraIssue → available transitions
5	Match event → target transition (see references/transition-mapping.md)
6	Plan mode: show plan. Execute mode: AskUserQuestion → transitionJiraIssue

See references/transition-mapping.md for event vocabulary, regex patterns, and resolution algorithm.

Plan output (default):

## Transition Plan

- Issue: OK-51513 "Add user profile page"
- Current: To Do
- Event: start_work
- Target: In Progress (transition id: 21)

Execute? /jira transition OK-51513 --event start_work --execute

Subcommand: create

Step	Action
1	Extract project key from input (bare key like OK, or from issue key prefix)
2	Resolve cloudId
3	getJiraProjectIssueTypesMetadata(cloudId, projectKey) → list available types
4	Validate issue type against available types (case-insensitive match)
5	Format description as markdown (see references/create-policy.md)
6	Plan mode: display creation plan. Execute mode: AskUserQuestion → createJiraIssue

Input sources (both supported):

• --summary and --description flags: explicit values
• Context inference: extract summary and description from user's prompt (structured content like Background, Items, etc.)

MCP call (createJiraIssue):

Parameter	Source
cloudId	Resolved via step 2
projectKey	From input
issueTypeName	Validated against available types
summary	From --summary or context
description	Formatted markdown from --description or context
contentFormat	Always "markdown"

Plan output (default):

## Create Issue Plan

- Project: OK
- Type: Task
- Summary: P1 Hardening — Quote state machine + Recovery Worker
- Description: (preview first 200 chars...)

Execute? /jira create OK --summary "..." --type Task --execute

Execute output:

✅ Created: OK-51514
https://yourorg.atlassian.net/browse/OK-51514

See references/create-policy.md for description format guidelines, project key extraction, and issue type validation.

Graceful Degradation

Failure	Message
MCP tools not available	"Atlassian MCP not connected. Enable Atlassian integration in claude.ai settings."
OAuth expired	"Atlassian authorization expired. Please re-authorize."
Issue not found	"Issue <KEY> not found. Verify the key and your access permissions."
Transition not available	"Cannot execute <event> from current status <status>. Available transitions: ..."
Network error	"Atlassian API unreachable. Please retry later."
Project not found	"Project '' not accessible. Check key and permissions."
Issue type not available	"Type '' not in project ''. Available: [list from metadata]"

Examples

/jira view OK-51513
→ Displays issue details (summary, status, assignee, priority, type, description)

/jira branch OK-51513
→ Plan: feat/OK-51513-add-user-profile-page

/jira branch OK-51513 --type fix --execute
→ Executes: git checkout -b fix/OK-51513-add-user-profile-page

/jira transition OK-51513 --event start_work
→ Plan: To Do → In Progress

/jira transition OK-51513 --event pr_merged --execute --comment "Merged via PR #42"
→ Executes transition + adds comment

/jira create OK --summary "Fix login timeout" --type Bug
→ Plan: Create Bug in OK

/jira create OK --summary "Add user dashboard" --type Story --description "## Background\nDashboard needed for..." --execute
→ ✅ Created: OK-51515