jira-writer

What this skill does

# Jira Writer Skill

## Overview

This skill enables reading, searching, creating, and modifying Jira Cloud tickets. You can fetch issue details, search with JQL queries, list projects and issue types, look up users, and view issue transitions. When writing content that includes Mermaid diagram code blocks, diagrams are automatically converted to PNG images and embedded in the ticket description.

### Capabilities

#### Read & Search
- Fetch issue details by key (summary, description, status, assignee, etc.)
- Search issues using JQL queries
- List visible Jira projects
- Get available issue types for a project
- Get available status transitions for an issue
- Look up Jira users by name or email
- Get remote/linked issues for a ticket

#### Create & Update
- Create new Jira tickets with structured content
- Update existing ticket descriptions (append, replace, or insert at location)
- Add comments to existing tickets
- Transition issue status
- Parse markdown files and convert to Jira-compatible ADF
- Automatically detect and convert Mermaid diagrams to embedded images
- Batch processing for multiple diagrams in a single request

### Trigger Conditions

This skill activates contextually when:

- User asks to **read, view, fetch, or get** a Jira issue (e.g., "show me PROJ-123", "what's the status of PROJ-456")
- User asks to **search or find** Jira issues (e.g., "find open bugs in PROJECT", "search Jira for...")
- User asks to **list projects**, **look up users**, or **check issue types**
- User asks to **create** a Jira ticket
- User asks to **update/modify** a Jira ticket description
- User provides content (text or markdown file) to write to a Jira ticket
- Content contains ` ```mermaid ``` ` code blocks that need embedding

### Issue Resolution

- If a Jira issue is already in the conversation (fetched, discussed), use it automatically
- If multiple issues are in context, ask which one to target
- If no issue in context, ask the user to specify or offer to create new

## Prerequisites

Before executing Jira operations, verify these dependencies:

### API Selection: REST API Primary, MCP Fallback

This skill uses a **hybrid approach** with REST API as the primary method:

| Priority | Method | When Used |
|----------|--------|-----------|
| **1st** | REST API | Always tried first (requires `JIRA_DOMAIN` + `JIRA_API_KEY`) |
| **2nd** | Atlassian MCP | Fallback when REST fails or isn't configured |

**Decision logic:**
```
IF JIRA_DOMAIN and JIRA_API_KEY configured:
    TRY REST API first
    IF REST fails:
        FALL BACK to MCP (if available)
ELSE:
    USE MCP directly (if available)
    IF MCP unavailable:
        REPORT error with setup instructions
```

### Required for REST API (Primary): JIRA_API_KEY

REST API is the recommended primary method for all operations.

**Check:** Verify environment variable `JIRA_API_KEY` exists.

**Format:** `email:api_token` (plain text, NOT base64 encoded)
- Generate API token at: https://id.atlassian.com/manage-profile/security/api-tokens
- Set as: `export JIRA_API_KEY="[email protected]:your_api_token"`

**IMPORTANT:** Store the raw `email:api_token` string. The upload scripts handle base64 encoding internally.

### Required for REST API (Primary): JIRA_DOMAIN

**Check:** Verify environment variable `JIRA_DOMAIN` exists (e.g., `company.atlassian.net`).

**If missing:** Ask user to provide their Jira domain.

### Optional Fallback: Atlassian MCP

The Atlassian MCP provides Jira API access as a fallback when REST API is unavailable.

**Check:** Attempt to use any `mcp__atlassian__*` tool.

**If unavailable and REST also unavailable:**
```
Neither REST API nor Atlassian MCP is configured.

For REST API (recommended):
1. Generate an API token at https://id.atlassian.com/manage-profile/security/api-tokens
2. Set environment variables:
   export JIRA_DOMAIN="company.atlassian.net"
   export JIRA_API_KEY="[email protected]:your_api_token"

For MCP fallback:
1. Install the MCP from the Atlassian marketplace
2. Configure authentication in your Claude Code MCP settings
3. Restart Claude Code
```

### Content Type and API Selection

Use a **content-based approach** for API selection:

| Content Type | API to Use | Reason |
|--------------|------------|--------|
| Headings, paragraphs, text | REST or MCP | Both work |
| Bullet lists, numbered lists | REST or MCP | Both work |
| Tables | REST or MCP | Both work |
| Code blocks | REST or MCP | Both work |
| Bold, italic, links | REST or MCP | Both work |
| **Checkboxes** (`- [ ]`, `- [x]`) | **REST API** | MCP converts to escaped text, not interactive taskList |
| **Images/Mermaid diagrams** | **REST API** | MCP cannot handle mediaSingle nodes |
| **External media** | **REST API** | MCP cannot embed media |
| **Attachments** | **REST API only** | MCP cannot upload files |

**Decision logic:**
```
SCAN content for:
  - Checkbox patterns: `- [ ]` or `- [x]` or `* [ ]` or `* [x]`
  - Mermaid blocks: ```mermaid
  - Image references or embedded media
  - Attachments to upload

IF any complex content found:
    USE REST API (required, no fallback)
ELSE:
    USE REST API first
    IF REST fails: FALL BACK to MCP
```

### Required for Diagrams: mermaid-cli

The `mmdc` command converts Mermaid syntax to PNG.

**Check (deferred until first diagram):**
```bash
which mmdc
```

**If missing:**
```
Mermaid CLI (mmdc) not found. Install it?

Run: npm install -g @mermaid-js/mermaid-cli

[If user declines, skip diagram processing with warning]
```

**Cache result:** After first check, remember mmdc availability for session.

### Graceful Degradation

| Missing | Behavior |
|---------|----------|
| REST API credentials | Fall back to MCP; if MCP unavailable, stop with setup instructions |
| MCP | REST API handles everything (no impact if REST configured) |
| Both REST and MCP | Skill cannot function; stop with setup instructions |
| JIRA_API_KEY only | Text operations via MCP; diagrams/checkboxes skipped with warning |
| mmdc | Diagrams skipped with warning; offer installation |

### Helper Scripts

The following scripts automate operations (located in `scripts/` directory):

#### How to invoke (IMPORTANT)

Call the plugin by its **bare command name `jira-writer`** — e.g. `jira-writer get_issue PROJ-123`. The plugin ships a `bin/jira-writer` launcher that Claude Code automatically adds to the Bash tool's `PATH`, so it resolves from any working directory.

**Do NOT prefix the command with `$CLAUDE_PLUGIN_ROOT` or an absolute script path.** `$CLAUDE_PLUGIN_ROOT` is exported only to hook and MCP subprocesses, never to the Bash tool shell — using it expands to an empty path and the call fails every time. The `bin/jira-writer` launcher exists precisely so you never need that variable.

All operations go through the `jira-writer` launcher, which forwards to `jira-api-wrapper.sh`. The low-level functions in `jira-rest-api.sh` are sourced by the wrapper and are not invoked directly. The diagnostic and mermaid helpers are reached via the reserved subcommands `jira-writer doctor`, `jira-writer connection-test`, `jira-writer mermaid`, and `jira-writer mermaid-batch`.

#### Troubleshooting

**`jira-writer: command not found`, "jira-writer scripts missing", or a raw "No such file or directory"**
The plugin updated during this session, so the cached `PATH` entry points at a
directory that no longer exists. **Restart Claude Code** to refresh it. As a
one-off fallback within the current session, the scripts live under this skill's
own base directory — run `"<skill base dir>/scripts/jira-api-wrapper.sh" <op>`
(the base directory is provided to you when this skill loads).

#### Primary Scripts

**jira-api-wrapper.sh** (USE THIS)
```bash
# Create issue - accepts positional args; --desc-file and --markdown convert to ADF automatically
jira-writer create_issue PROJECT_KEY TYPE SUMMARY [DESC] [--desc-file PATH] [--markdown] [--parent KEY]
jira-writer create_issue PROJ Task "Fix login bug" "Users cann