Jira Planner Skill

jira-planner — Claude Code skill for Jira automation

Generic, tenant-agnostic skill for any Jira Cloud instance. Drives:

• New-task flow (12-step process): freeform problem → researched, estimated, structured Jira ticket.
• Read ops — view, search, comments, watchers, links — via acli (optimized) or MCP (default).
• Write ops — create / edit / transition / link / comment — MCP-default, acli optimization where viable.

Transport: MCP-default (mcp__claude_ai_Atlassian__* if connected, else mcp__jira__*); acli opportunistically when authed and faster.

TL;DR — 5 steps

# 1. Install Atlassian CLI (optional but recommended; macOS shown)
brew install --cask atlassian-acli   # or follow https://developer.atlassian.com/cloud/acli/

# 2. Authenticate acli
acli jira auth login                 # opens browser; pick your .atlassian.net

# 3. Connect an Atlassian MCP server to Claude Code (see "MCP setup" below)
#    — pick ONE of the two flavours, OAuth or API-token.

# 4. Clone the skill
git clone https://github.com/Lumyk/jira-planner-skill.git ~/.claude/skills/jira-planner

# 5. Inside Claude Code, run:
/jira-planner setup

Done — the skill writes config.local.yaml, then you can ask it to create / view / edit Jira tickets.

---

Detailed setup

1. Claude Code

Install Claude Code per Anthropic's instructions. Verify claude --version prints something. Skills live under ~/.claude/skills/.

2. Atlassian CLI — acli (optional but recommended)

acli is allowlisted by default, so read ops (view ticket, search, list comments/watchers/links) don't trigger an approval prompt every time. The skill works without acli — it falls back to MCP for everything — but you'll pay an approval prompt per read.

Install:

• macOS: brew install --cask atlassian-acli
• Linux / Windows / other: follow Atlassian's official install guide at https://developer.atlassian.com/cloud/acli/

Authenticate:

acli jira auth login

This opens your browser, you pick the Atlassian site (.atlassian.net), and grant acli access. Verify:

acli jira auth status
# Expect: ✓ Authenticated as  at 

If you don't install acli, the skill detects this on first run and silently falls through to MCP for every op.

3. MCP setup — pick ONE

The skill prefers the Atlassian remote MCP server (namespace mcp__claude_ai_Atlassian__*) and falls back to mcp-atlassian (namespace mcp__jira__*) if the first isn't connected. Either one works.

Option A — Atlassian remote MCP server (OAuth, recommended)

Atlassian publishes an official MCP server you can wire into Claude Code. Follow the current docs at https://www.atlassian.com/platform/remote-mcp-server (or whatever the latest official URL is — Atlassian moves these around). The typical flow is:

1. In Claude Code, run /mcp (or open settings → MCP) and add the Atlassian server URL.
2. Authorize via OAuth in the browser.
3. Confirm tools appear with mcp__claude_ai_Atlassian__ prefix (e.g. mcp__claude_ai_Atlassian__getJiraIssue).

Inside Claude Code you can also use the CLI:

claude mcp add atlassian --transport sse 

(Replace `` with the value Atlassian publishes in their MCP docs.)

Option B — mcp-atlassian (API token, self-hosted)

The community-maintained mcp-atlassian server runs locally and authenticates via a personal API token. Good for self-hosted setups or when you don't want OAuth.

# Install via uv (recommended) or pip
uvx mcp-atlassian --jira-url https://.atlassian.net \
                  --jira-username @example.com \
                  --jira-token 

Generate an API token at https://id.atlassian.com/manage-profile/security/api-tokens. Wire the command above into Claude Code's MCP config (~/.claude.json or per-project .mcp.json):

{
  "mcpServers": {
    "jira": {
      "command": "uvx",
      "args": [
        "mcp-atlassian",
        "--jira-url", "https://.atlassian.net",
        "--jira-username", "@example.com",
        "--jira-token", ""
      ]
    }
  }
}

Restart Claude Code. Tools should appear with mcp__jira__ prefix.

> Don't commit the API token. Either keep .mcp.json gitignored or use env vars (--jira-token $JIRA_TOKEN).

Sanity check

Inside Claude Code, ask: "Show me a list of Jira projects I have access to". It should call mcp__claude_ai_Atlassian__getVisibleJiraProjects (or mcp__jira__jira_get_all_projects) and return a list. If you get "tool not available", the MCP server isn't connected.

4. Clone the skill

git clone https://github.com/Lumyk/jira-planner-skill.git ~/.claude/skills/jira-planner

Or, if you keep your skill repos elsewhere, symlink:

ln -s ~/repos/jira-planner-skill ~/.claude/skills/jira-planner

Either way, ~/.claude/skills/jira-planner/SKILL.md must exist for Claude Code to discover the skill.

5. First-run configuration

The skill is inert until config.local.yaml exists. Two ways to populate it:

Option A — guided discovery (recommended on first install)

In Claude Code:

/jira-planner setup

The skill probes your Atlassian site via acli + MCP, asks 4 questions (site, project keys, body language, research base dir), pulls custom field IDs and option IDs via MCP createmeta, and writes config.local.yaml. ~2 minutes.

You can also pick minimal bootstrap when prompted — discover only enough to create one ticket, defer the rest. Useful when you just want to file something fast.

Option B — paste a ready YAML

If a colleague already runs the skill for the same Jira instance, ask them for their config.local.yaml. Paste it into Claude Code and say "this is my jira-planner config". The skill validates it against the schema (config.example.yaml) and writes it.

> config.local.yaml is gitignored. Never commit a populated copy — it contains cloudId and custom field IDs that may be sensitive depending on your org.

6. Try it

Create a Bug ticket: VCField doesn't dismiss keyboard on tap outside. Priority Medium, Estimate 4h.

The skill walks the 12-step flow, asks you to confirm the draft, creates the ticket via MCP, then verifies every field landed correctly via a read call.

---

Files

| File | Public? | Purpose | |---|---|---| | SKILL.md | yes | Router. Loaded by Claude Code on trigger. | | process.md | yes | 12-step new-task flow. | | transport.md | yes | MCP/acli matrix, gotchas, ADF, link semantics, verify pattern. | | body-templates.md | yes | Bug / Feature / Task / Other body skeletons. Multi-lang via placeholders. | | setup.md | yes | First-run discovery workflow. | | config.example.yaml | yes | Schema template with placeholders. | | README.md | yes | This file. | | .gitignore | yes | Excludes config.local.*, *.local.*, *.bak. | | config.local.yaml | no (gitignored) | Tenant config: Cloud ID, projects, custom fields, automation, research repos, body language. |

Updating config

The skill writes back to config.local.yaml when it discovers new option IDs, field IDs, or automation behaviors during a session (with your explicit confirmation). To force a fresh re-discovery:

/jira-planner setup --refresh

This re-pulls metadata but keeps user preferences (body language, research base dir, API docs, and the user: section) unchanged.

User preferences and persistent memory (user: section)

config.local.yaml has a user-owned user: section that the skill reads on every session start and applies contextually. The skill never overwrites it without explicit confirmation.

user:
  defaults:
    priority: Medium                 # fallback when you don't specify
    assignee: current                # fallback assignee — 'current' = authed user
  notes:                             # free-text reminders — persistent memory
    - "Mobile = = + ="
    - "Always @-mention  on Bug create in "
    - "Regression bugs: append 'Worked in vX' to the body"

defaults — used as fallbacks during ticket creation when you don't specify priority/assignee.

notes[] — free-text persistent memory. The skill scans every entry at step 2 (clarify) and surfaces any whose subject overlaps with the current ticket: "Note from your config says: 'X'. Apply?" You can:

• Edit the file directly to add/remove notes.
• Tell the skill "remember this for jira-planner: …" — it proposes a diff and appends with your confirmation.

This is where aliases, auto-mention rules, body conventions, link patterns, and any other "how I work" reminders belong. Keep entries one line each, plain language.

Troubleshooting

| Symptom | Cause | Fix | |---|---|---| | Tool 'mcp__claude_ai_Atlassian__*' not found | Atlassian MCP server not connected. | Add it via /mcp or fall back to mcp-atlassian (mcp__jira__*). | | acli: command not found | acli not installed. | Skip — skill falls back to MCP. Or install per step 2. | | Skill creates a ticket but the custom field is empty | The create screen for that issue type doesn't expose that field; Jira silently drops it. | The skill auto-detects this in step 12 (verify) and patches via editJiraIssue. If it doesn't, run /jira-planner setup --refresh and re-try. | | Doubled [X] [X] summary prefix | Jira automation prepends the prefix; skill also prepended it. | The skill is supposed to submit summary WITHOUT the automation prefix. If you see this, the automation.summaryPrefixFromField entry in config.local.yaml is missing or wrong. Run --refresh and confirm the automation when prompted. | | acli authed to a different site than config.site | You logged into the wrong site, or you changed sites and didn't re-auth. | acli jira auth login again; pick the site matching config.site. The skill detects this mismatch at setup time too. |

Requirements

• Claude Code with the Skill tool enabled.
• An Atlassian MCP server wired up (either mcp__claude_ai_Atlassian__* or mcp__jira__*).
• acli (optional) for faster reads — brew install --cask atlassian-acli on macOS.

License

MIT.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lumyk
• Source: Lumyk/jira-planner-skill
• License: MIT

Install and usage instructions live in the source repository linked above.