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 [email protected]: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

Largest Agentic Marketplace for AI Agent Skills and SpillWave: Leaders in AI Agent Development.

---

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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]"
      }
    }
  }
}

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
• Track epic progress
• Link issues to epics
• Sprint planning workflows

Collaboration

• Add comments with Markdown support
• Upload attachments
• Create issue links (Blocks, Relates, Duplicates)
• Create remote links (Confluence, web URLs)

Custom Field Discovery

• Search fields by keyword
• Discover custom field IDs and types
• Validate field formats
• Handle project-specific fields

Batch Operations

• Create multiple issues efficiently
• Get changelogs for multiple issues
• Bulk operations on issue sets

---

File Structure

~/.claude/skills/jira/
├── CLAUDE.md                     # Architecture guide for Claude Code
├── README.md                     # This file
├── SKILL.md                      # Detailed skill documentation
├── templates/
│   └── issue_creation.json       # Issue creation templates
├── references/
│   └── jql_guide.md             # Comprehensive JQL reference
├── scripts/                      # Utility scripts (future)
└── assets/                       # Additional resources

Key Documentation

SKILL.md (Primary Reference)

Comprehensive workflow documentation including:

• Issue creation workflow (step-by-step)
• Custom field discovery methodology
• JQL query patterns
• Agile/Scrum operations
• Troubleshooting guide
• Best practices

references/jql_guide.md

Complete JQL (JIRA Query Language) reference:

• All operators and functions
• Date/time queries
• Historical search operators
• Sprint and epic queries
• 50+ common use cases
• Best practices and common pitfalls

templates/issue_creation.json

Standard templates for:

• Basic tasks
• Bug reports with reproduction steps
• User stories with acceptance criteria
• Epics
• Subtasks
• Issues with custom fields
• Batch creation examples

CLAUDE.md

Architecture and patterns guide for Claude Code instances, documenting:

• Core workflow patterns
• Critical validation steps
• Custom field discovery methodology
• Common command patterns

---

Common Workflows

Creating Issues

"Create a JIRA task in project ENG for implementing rate limiting"
"Create a bug in project API: Login endpoint returns 500 error"
"Create an epic in project MOBILE for offline support feature"

Searching Issues

"Search JIRA for all open bugs in project ENG assigned to me"
"Find all issues in the current sprint"
"Show me overdue issues in project API"
"Find all stories without acceptance criteria"

Managing Workflows

"Move ENG-123 to In Progress"
"Transition API-456 to Done"
"Show available transitions for MOBILE-789"

Agile Operations

"Show me the active sprint for board 1000"
"Create a sprint named 'Sprint 15' for board 1000"
"Add ENG-123 and ENG-124 to the current sprint"
"Link story ENG-200 to epic ENG-100"

Custom Field Discovery

"Find custom fields with keyword 'owning team'"
"Search for fields containing 'acceptance criteria'"
"What custom fields are available in project ENG?"

---

Best Practices

1. Always Validate Project Keys

Never assume project keys - always verify before operations:

"What projects are available in JIRA?"

2. Discover Custom Fields

Use field search before working with custom fields:

"Find custom fields with keyword 'story points'"

3. Use JQL for Complex Searches

Leverage JQL functions and operators:

"Search JIRA with: project = ENG AND status = 'In Progress' AND assignee = currentUser()"

4. Batch Operations for Efficiency

Create multiple related tickets at once:

"Create 5 tasks in project ENG for: setup, config, test, docs, deploy"

5. Link Related Issues

Always link related work:

"Create issue link: ENG-123 blocks ENG-124"

---

Troubleshooting

"Project not found"

• Use "What projects are available?" to see available projects
• Check JIRA_PROJECTS_FILTER environment variable in .mcp.json
• Verify project key is exact (case-sensitive)

"Field required" errors

• Ask: "Search for required fields in project ENG"
• Check project configuration
• Some fields required by workflow, not project

"Invalid transition" errors

• Ask: "Show available transitions for ENG-123"
• Current status matters for available transitions
• Check permissions

Custom fields not working

• Ask: "Find custom fields with keyword 'team'"
• Use discovered field ID format: customfield_10010
• Check if field applies to the issue type

Multiple JIRA instances

• Verify correct .mcp.json is loaded for workspace/project
• Check JIRA_URL in environment configuration
• Ensure API token matches the JIRA instance

---

Integration with Other Skills

This JIRA skill can work alongside other Claude Code skills:

Meeting Notes Skill

Process action items into JIRA tickets:

"Create JIRA tickets from these meeting action items in project ENG"

Project Management Skills

Reference project context when creating tickets:

"Create ticket in the project we're currently working on"

Documentation Skills

Link JIRA tickets to documentation:

"Create remote link from ENG-123 to our Confluence page"

---

Advanced Usage

Custom JQL Queries

See references/jql_guide.md for:

• 50+ common JQL patterns
• Historical search operators
• Sprint and epic management
• Date functions and relative time
• Best practices and pitfalls

Batch Operations

See templates/issue_creation.json for:

• Batch creation examples
• Field format reference
• Multi-issue workflows

Automation Patterns

The scripts/ directory can contain custom automation:

• Bulk issue creation from CSV
• Sprint reports
• Issue analysis and metrics
• Custom workflows

---

Updates and Maintenance

Updating the Skill

cd ~/.claude/skills/jira  # or workspace/project path
git pull origin main

Customizing for Your Team

You can customize this skill by:

1. Modifying templates in templates/issue_creation.json
2. Adding custom JQL patterns to references/jql_guide.md
3. Documenting team workflows in SKILL.md
4. Creating automation scripts in scripts/
5. Adjusting field mappings for project-specific custom fields

Version Control

Keep skill customizations in version control:

cd ~/.claude/skills/jira  # or workspace path
git remote add team-fork https://github.com/your-org/jira-skill-fork.git
git push team-fork main

This allows sharing customizations across your team.

---

Support

For issues or questions:

1. Check SKILL.md for detailed workflows
2. Review references/jql_guide.md for JQL help
3. Consult Atlassian MCP documentation
4. Verify .mcp.json configuration
5. Check JIRA permissions for your account
6. Review CLAUDE.md for architecture patterns

---

Contributing

To improve this skill:

1. Document new workflows in SKILL.md
2. Add JQL patterns to references/jql_guide.md
3. Create templates in templates/
4. Share automation scripts in scripts/
5. Update best practices based on experience

---

License

This skill is designed for use with Claude Code and the Atlassian MCP server.

---

Related Resources

• Claude Code Documentation
• Model Context Protocol
• Atlassian JIRA Documentation
• JQL Reference
• Atlassian MCP Server
• SkillzWave Marketplace
• SpillWave Solutions