sd0xdev/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 '<KEY>' not accessible. Check key and permissions." | | Issue type not available | "Type '<type>' not in project '<KEY>'. 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