JIRA Skill for Claude Code

A comprehensive Claude Code skill that provides intelligent guidance for managing JIRA issues, projects, and workflows through the Atlassian MCP server.

Table of Contents

• What is a Skill?
• How This Skill Works
• Installing with Skilz
• Manual Installation
• Prerequisites
• Quick Start
• Features
• Common Workflows
• Best Practices
• Troubleshooting
• Contributing

---

What is a Skill?

A skill is an instruction manual that teaches Claude Code how to use MCP (Model Context Protocol) tools effectively. Think of it this way:

• MCP Server (Atlassian MCP) = The tool that provides access to JIRA APIs
• Skill (this repository) = The instruction manual that guides Claude on best practices, workflows, and patterns for using that tool

Claude Code can discover and use MCP tools automatically, but skills provide the critical context, workflows, and domain expertise that make interactions efficient, reliable, and consistent with your team's practices.

How This Skill Works

This skill works hand-in-glove with the Atlassian MCP server (mcp__atlassian). The MCP provides raw access to JIRA's API capabilities, while this skill provides:

• Structured workflows for common JIRA operations
• Field discovery patterns for handling custom fields
• JQL query construction guidance and examples
• Best practices for issue creation, transitions, and agile operations
• Troubleshooting guides for common errors
• Validation patterns to ensure reliable operations

When you ask Claude Code to work with JIRA, this skill ensures operations follow proven patterns, validate inputs properly, and handle JIRA's complexity gracefully.

---

Installing with Skilz (Universal Installer)

The recommended way to install this skill across different AI coding agents is using the skilz universal installer.

Install Skilz

pip install skilz

This skill supports Agent Skill Standard which means it supports 14 plus coding agents including Claude Code, OpenAI Codex, Cursor and Gemini.

Git URL Options

You can use either -g or --git with HTTPS or SSH URLs:

# HTTPS URL
skilz install -g https://github.com/SpillwaveSolutions/jira

# SSH URL
skilz install --git git@github.com:SpillwaveSolutions/jira.git

Claude Code

Install to user home (available in all projects):

skilz install -g https://github.com/SpillwaveSolutions/jira

Install to current project only:

skilz install -g https://github.com/SpillwaveSolutions/jira --project

OpenCode

Install for OpenCode:

skilz install -g https://github.com/SpillwaveSolutions/jira --agent opencode

Project-level install:

skilz install -g https://github.com/SpillwaveSolutions/jira --project --agent opencode

Gemini

Project-level install for Gemini:

skilz install -g https://github.com/SpillwaveSolutions/jira --agent gemini

OpenAI Codex

Install for OpenAI Codex:

skilz install -g https://github.com/SpillwaveSolutions/jira --agent codex

Project-level install:

skilz install -g https://github.com/SpillwaveSolutions/jira --project --agent codex

Install from Skillzwave Marketplace

# Claude to user home dir ~/.claude/skills
skilz install SpillwaveSolutions_jira/jira

# Claude skill in project folder ./claude/skills
skilz install SpillwaveSolutions_jira/jira --project

# OpenCode install to user home dir ~/.config/opencode/skills
skilz install SpillwaveSolutions_jira/jira --agent opencode

# OpenCode project level
skilz install SpillwaveSolutions_jira/jira --agent opencode --project

# OpenAI Codex install to user home dir ~/.codex/skills
skilz install SpillwaveSolutions_jira/jira

# OpenAI Codex project level ./.codex/skills
skilz install SpillwaveSolutions_jira/jira --agent opencode --project


# Gemini CLI (project level) -- only works with project level
skilz install SpillwaveSolutions_jira/jira --agent gemini

See this site skill Listing to see how to install this exact skill to 14+ different coding agents.

Other Supported Agents

Skilz supports 14+ coding agents including Claude Code, OpenAI Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot CLI, Windsurf, Qwen Code, Aidr, and more.

For the full list of supported platforms, visit SkillzWave.ai/platforms or see the skilz-cli GitHub repository

<a href="https://skillzwave.ai/">Largest Agentic Marketplace for AI Agent Skills</a> and <a href="https://spillwave.com/">SpillWave: Leaders in AI Agent Development.</a>

---

Manual Installation

Installation Levels

This skill can be installed at multiple levels depending on your organizational structure and needs:

1. Global Installation (User Level)

Install in your home directory for use across all projects:

~/.claude/skills/jira/

Use case: You work with a single JIRA instance across all projects.

2. Project-Level Installation

Install within a specific project directory:

/path/to/project/.claude/skills/jira/

Use case: Project-specific JIRA configuration or custom workflows that differ from other projects.

3. Workspace-Level Installation

Install at a workspace directory that groups multiple related projects:

~/workspace/acme-corp/.claude/skills/jira/
~/workspace/tech-startup/.claude/skills/jira/

Use case:

• Client-based workspaces: Different skills/configs for different clients
• Department-based workspaces: Engineering vs Operations vs Support teams
• Company-based workspaces: Multiple clients with different JIRA instances

Installation Priority

Claude Code follows this priority order when loading skills:

1. Project-level (.claude/skills/ in current directory)
2. Workspace-level (.claude/skills/ in parent directories)
3. Global-level (~/.claude/skills/ in home directory)

This allows project-specific customizations to override workspace or global defaults.

---

Multi-Instance JIRA Support

For organizations that need to connect to multiple JIRA instances (multiple clients, acquisitions, different departments), you can configure the Atlassian MCP at different levels using .mcp.json files.

Example: Multiple Client Workspaces

Scenario: You're a consultant working with multiple clients, each with their own Atlassian instance.

# Client 1 workspace
~/clients/acme-industries/
├── .mcp.json              # JIRA config for acme-industries.atlassian.net
├── .claude/
│   ├── skills/jira/       # Client-specific JIRA workflows (optional)
│   └── settings.local.json
├── project-alpha/
└── project-beta/

# Client 2 workspace
~/clients/globex-corp/
├── .mcp.json              # JIRA config for globex.atlassian.net
├── .claude/
│   ├── skills/jira/       # Client-specific JIRA workflows (optional)
│   └── settings.local.json
├── web-app/
└── mobile-app/

Example: Department-Based Workspaces

Scenario: Large organization with different JIRA instances per department.

# Engineering workspace
~/workspaces/engineering/
├── .mcp.json              # JIRA config for eng.company.atlassian.net
├── .claude/skills/jira/   # Engineering-specific workflows
├── backend-services/
└── frontend-apps/

# Operations workspace
~/workspaces/operations/
├── .mcp.json              # JIRA config for ops.company.atlassian.net
├── .claude/skills/jira/   # Operations-specific workflows
├── infrastructure/
└── monitoring/

.mcp.json Configuration

Each workspace can have its own .mcp.json file with JIRA credentials:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-atlassian"],
      "env": {
        "JIRA_URL": "https://acme-industries.atlassian.net",
        "JIRA_API_TOKEN": "your-api-token-here",
        "JIRA_EMAIL": "your-email@acme-industries.com",
        "JIRA_PROJECTS_FILTER": "ENG,API,WEB"
      }
    }
  }
}

Configuration Priority

Claude Code uses this priority for .mcp.json files:

1. Project directory (most specific)
2. Workspace directory (parent directories)
3. Global config (~/.claude/mcp.json)

This allows you to:

• Connect to different JIRA instances per workspace
• Use different credentials per client/department
• Override global JIRA settings for specific projects
• Maintain separate JIRA configurations without conflicts

---

Prerequisites

Required MCP Server

The Atlassian MCP server must be configured in Claude Code:

npm install -g @modelcontextprotocol/server-atlassian

Configure in ~/.claude/mcp.json or workspace-level .mcp.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-atlassian"],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_PROJECTS_FILTER": "PROJ1,PROJ2"
      }
    }
  }
}

JIRA API Token

Generate a JIRA API token:

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Copy the token and add to your .mcp.json configuration

Permissions

Ensure your JIRA account has appropriate permissions for:

• Creating/updating issues
• Searching issues
• Managing sprints/epics (if using Agile features)
• Transitioning issues through workflows

---

Quick Start

1. Install the Skill

Using Skilz (recommended):

pip install skilz
skilz install -g https://github.com/SpillwaveSolutions/jira

Or manually:

# Global installation
mkdir -p ~/.claude/skills/
cd ~/.claude/skills/
git clone https://github.com/SpillwaveSolutions/jira.git jira

2. Configure Atlassian MCP

Create or update .mcp.json at the appropriate level:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-atlassian"],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_API_TOKEN": "your-token-here",
        "JIRA_EMAIL": "your-email@example.com"
      }
    }
  }
}

3. Start Using JIRA with Claude Code

Simply ask Claude Code to work with JIRA:

"Create a JIRA task in project ENG for implementing user authentication"
"Search JIRA for all open bugs assigned to me"
"Move ticket ENG-123 to Done"
"Show me the active sprint for our board"

Claude Code will automatically:

• Validate project keys
• Discover custom fields
• Construct proper JQL queries
• Handle workflows and transitions
• Follow best practices from this skill

---

Features

Issue Management

• Create issues (Task, Bug, Story, Epic, Subtask)
• Update issue fields (priority, assignee, custom fields)
• Search with JQL (comprehensive query patterns)
• Get issue details
• Delete issues
• Batch create multiple issues

Workflow Operations

• Get available transitions for an issue
• Transition issues between states
• Add required fields during transitions
• Handle workflow-specific requirements

Agile/Scrum

• Work with boards and sprints
• Create and update sprints
• Move issues to sprints