Jira

JIRA Management Skill

A comprehensive Claude Code skill for managing JIRA issues, projects, and workflows using the Atlassian MCP server.

Table of Contents

• Overview
• Prerequisites
• Skill Workflow
• Issue Creation
• Issue Search and Management
• Workflow and Transitions
• Agile/Scrum Operations
• Linking and Relationships
• Comments and Collaboration
• Batch Operations
• Project and Version Management
• Best Practices
• Common Use Cases
• References
• Troubleshooting

Overview

This skill provides intelligent JIRA management capabilities including:

• Creating and managing issues with proper field validation
• Searching and filtering issues using JQL
• Managing workflows and transitions
• Working with epics, sprints, and agile boards
• Adding comments, attachments, and links
• Batch operations for efficiency
• Project and version management

Prerequisites

Required MCP Server

• Atlassian MCP (mcp__atlassian) must be configured in Claude Code
• JIRA credentials (API token or OAuth) must be set up
• Appropriate JIRA permissions for the operations you need

Environment Configuration

The Atlassian MCP may use environment variables:

• JIRA_URL: Your JIRA instance URL
• JIRA_API_TOKEN: API token for authentication
• JIRA_EMAIL: Email associated with API token
• JIRA_PROJECTS_FILTER: (Optional) Comma-separated project keys to filter

Skill Workflow

1. Issue Creation Workflow

When creating JIRA issues, follow this sequence:

Step 1: Gather Requirements

Ask the user for:

• Project key (e.g., "PROJ", "DEV", "SUPPORT") - NEVER ASSUME
• Issue type (Task, Bug, Story, Epic, Subtask)
• Summary (title/description)
• Priority (if applicable)
• Assignee (optional - email, display name, or account ID)
• Additional fields (components, labels, custom fields)

Step 2: Validate Project

Use mcp__atlassian__jira_get_all_projects to:

• Verify project exists
• Get available projects if user unsure
• Confirm project key matches exactly

Step 3: Search Available Fields (if needed)

Use mcp__atlassian__jira_search_fields to find custom field names and IDs. See Custom Field Discovery for detailed methodology.

Step 4: Create Issue

Use mcp__atlassian__jira_create_issue with:

{
  "project_key": "PROJ",
  "summary": "Implement user authentication",
  "issue_type": "Task",
  "description": "Detailed description in Markdown format",
  "assignee": "user@example.com",
  "components": "Frontend,API",
  "additional_fields": {
    "priority": {"name": "High"},
    "labels": ["security", "authentication"],
    "parent": "PROJ-123"
  }
}

Step 5: Follow-up Actions (if needed)

• Link to epic: mcp__atlassian__jira_link_to_epic
• Add attachments: Include in update or create
• Add comments: mcp__atlassian__jira_add_comment
• Create issue links: mcp__atlassian__jira_create_issue_link

2. Issue Search and Management

Searching Issues

Use mcp__atlassian__jira_search with JQL. For comprehensive JQL documentation, see JQL Guide.

Essential JQL Patterns:

# Open issues in project
project = PROJ AND status = Open

# Your assigned issues
assignee = currentUser() AND status != Done

# Issues in current sprint
sprint IN openSprints()

# Recently updated
updated >= -7d AND project = PROJ

Parameters:

• jql: JQL query string
• fields: "summary,status,assignee,priority" or "*all"
• limit: Max results (1-50, default 10)
• start_at: Pagination offset

Getting Issue Details

Use mcp__atlassian__jira_get_issue:

• issue_key: "PROJ-123"
• fields: Comma-separated or "*all"
• expand: "renderedFields", "transitions", "changelog"
• comment_limit: Number of comments to include

Updating Issues

Use mcp__atlassian__jira_update_issue:

{
  "issue_key": "PROJ-123",
  "fields": {
    "summary": "Updated summary",
    "assignee": "user@example.com",
    "priority": {"name": "Critical"}
  },
  "additional_fields": {
    "labels": ["urgent", "hotfix"]
  },
  "attachments": "/path/to/file1.txt,/path/to/file2.pdf"
}

3. Workflow and Transitions

Get Available Transitions

Use mcp__atlassian__jira_get_transitions:

• Returns list of valid transitions for current issue state
• Each transition has an ID and name

Transition Issue

Use mcp__atlassian__jira_transition_issue:

{
  "issue_key": "PROJ-123",
  "transition_id": "31",
  "fields": {
    "resolution": {"name": "Fixed"}
  },
  "comment": "Moving to Done after completing implementation"
}

4. Agile/Scrum Operations

Working with Boards

1. Get boards: mcp__atlassian__jira_get_agile_boards

• Filter by: board_name, project_key, board_type (scrum/kanban)

2. Get board issues: mcp__atlassian__jira_get_board_issues

• Requires board_id and jql filter

Working with Sprints

1. Get sprints: mcp__atlassian__jira_get_sprints_from_board

• Filter by state: "active", "future", "closed"

2. Get sprint issues: mcp__atlassian__jira_get_sprint_issues

• Returns all issues in specified sprint

3. Create sprint: mcp__atlassian__jira_create_sprint

{
  "board_id": "1000",
  "sprint_name": "Sprint 15",
  "start_date": "2025-01-21T09:00:00.000+0000",
  "end_date": "2025-02-04T17:00:00.000+0000",
  "goal": "Complete authentication feature"
}

4. Update sprint: mcp__atlassian__jira_update_sprint

Working with Epics

1. Find epics: Use JQL: issuetype = Epic AND project = PROJ 2. Link to epic: mcp__atlassian__jira_link_to_epic 3. Find issues in epic: Use JQL: parent = EPIC-KEY

5. Linking and Relationships

Issue Links

Use mcp__atlassian__jira_create_issue_link:

{
  "link_type": "Blocks",
  "inward_issue_key": "PROJ-123",
  "outward_issue_key": "PROJ-456",
  "comment": "This issue blocks the other"
}

Get link types: mcp__atlassian__jira_get_link_types

Remote Links (Web/Confluence)

Use mcp__atlassian__jira_create_remote_issue_link:

{
  "issue_key": "PROJ-123",
  "url": "https://confluence.example.com/pages/123456",
  "title": "Technical Design Doc",
  "summary": "Detailed architecture documentation",
  "relationship": "documentation"
}

6. Comments and Collaboration

Add Comment

Use mcp__atlassian__jira_add_comment:

• Supports Markdown format
• Visible in issue activity

Get Comments

Use mcp__atlassian__jira_get_issue with appropriate fields

7. Batch Operations

Batch Create Issues

Use mcp__atlassian__jira_batch_create_issues:

{
  "issues": "[{\"project_key\":\"PROJ\",\"summary\":\"Task 1\",\"issue_type\":\"Task\"},{\"project_key\":\"PROJ\",\"summary\":\"Task 2\",\"issue_type\":\"Bug\"}]",
  "validate_only": false
}

Batch Get Changelogs

Use mcp__atlassian__jira_batch_get_changelogs:

• Get history for multiple issues
• Filter by specific fields
• Cloud only feature

8. Project and Version Management

List Projects

Use mcp__atlassian__jira_get_all_projects:

• Returns accessible projects
• Respects JIRA_PROJECTS_FILTER if configured

Get Project Issues

Use mcp__atlassian__jira_get_project_issues:

• Returns all issues for specific project
• Supports pagination

Version Management

1. Get versions: mcp__atlassian__jira_get_project_versions 2. Create version: mcp__atlassian__jira_create_version 3. Batch create: mcp__atlassian__jira_batch_create_versions

Best Practices

1. Always Validate Input

• Never assume project keys - always verify
• Use jira_search_fields to find custom field IDs
• Check available transitions before transitioning

2. Use Appropriate Field Selection

• Request only needed fields to reduce token usage
• Use "*all" sparingly, only when necessary
• Specify fields explicitly for better performance

3. JQL Query Construction

See JQL Guide for comprehensive documentation.

4. Error Handling

• Check for required fields before creating issues
• Validate transition IDs before executing
• Handle permission errors gracefully

5. Efficiency

• Use batch operations for multiple issues
• Paginate large result sets
• Use JQL filters to reduce result size

Common Use Cases

Create Story with Subtasks

1. Create Epic (if needed)
2. Create Story and link to Epic
3. Create multiple Subtasks with parent = Story key
4. Optionally add to sprint

Bug Triage Workflow

1. Search for bugs: issuetype = Bug AND status = Open
2. For each bug: Update priority, assign, add to sprint, transition

Sprint Planning

1. Get active sprint
2. Search backlog issues
3. Move selected issues to sprint
4. Update estimates and assign

Release Management

1. Create version for release
2. Search issues: fixVersion = "1.0.0"
3. Verify all are Done
4. Create release notes

References

See references/ directory for detailed documentation:

• jql_guide.md - Comprehensive JQL query guide
• custom_field_discovery.md - Custom field discovery methodology

See templates/ directory for:

• issue_creation.json - Standard issue creation templates

Troubleshooting

Common Issues

Issue: "Project not found"

• Verify project key is correct (case-sensitive)
• Use jira_get_all_projects to list available projects
• Check JIRA_PROJECTS_FILTER environment variable

Issue: "Field required but not provided"

• Use jira_search_fields to find required fields
• Check project configuration for mandatory fields
• Some fields may be required by workflow

Issue: "Invalid transition"

• Use jira_get_transitions to see available transitions
• Check current issue status
• Verify permissions for transition

Issue: "Custom field not found"

• See Custom Field Discovery for discovery methodology
• Format: customfield_10010
• Check if field applies to issue type

Skill Invocation

This skill is automatically invoked when users:

• Ask to "create a JIRA ticket/issue"
• Request "search JIRA for..."
• Say "update JIRA issue..."
• Request "move issue to..." or "transition..."
• Ask about "sprint", "epic", or "board" operations
• Request batch operations on JIRA issues

Notes

• The Atlassian MCP (mcp__atlassian) prefix is used for all tools
• All date/time values use ISO 8601 format
• JQL syntax is similar to SQL but has specific JIRA operators
• Cloud vs Server/Data Center may have feature differences

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
• 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

Custom Field Discovery Methodology

JIRA instances heavily customize their field schemas with custom fields that vary by organization, project, and issue type. These fields have opaque identifiers (e.g., customfield_10352) that must be discovered and mapped to human-readable names for automation.

The Challenge

Problem: You need to create tickets with specific fields, but you only know the human-readable name (e.g., "Owning Team", "Acceptance Criteria", "Risk Assessment") and not the custom field ID required by the API.

Symptom: Creating tickets fails with "field not found" or required fields are silently ignored because you're using the wrong identifier.

Discovery Workflow

Step 1: Search by Keyword

Use mcp__atlassian__jira_search_fields to find fields by partial name match:

{
  "keyword": "owning",
  "limit": 10
}

Returns:

[
  {
    "id": "customfield_11077",
    "name": "Owning Team",
    "custom": true,
    "schema": {
      "type": "option",
      "custom": "com.atlassian.jira.plugin.system.customfieldtypes:select"
    }
  }
]

Key Information Extracted:

• Field ID: customfield_11077 (use this in API calls)
• Field Name: "Owning Team" (human-readable)
• Field Type: option with select custom type (dropdown/single-select)
• Custom: true (not a standard JIRA field)

Step 2: Understand Field Type

The schema.type and schema.custom fields tell you how to format values:

Step 3: Test with Single Issue

Create a test issue using the discovered field ID:

{
  "project_key": "PROJ",
  "summary": "Test custom field",
  "issue_type": "Task",
  "additional_fields": {
    "customfield_11077": {
      "value": "Platform Team"
    }
  }
}

Verify: Check the created issue in JIRA UI to confirm the field populated correctly.

Step 4: Document the Mapping

Once verified, document the field mapping in a project-specific configuration file:

{
  "project_key": "PROJ",
  "custom_fields": {
    "owning_team": {
      "field_id": "customfield_11077",
      "field_name": "Owning Team",
      "field_type": "select",
      "required": true,
      "description": "Team responsible for this work"
    },
    "acceptance_criteria": {
      "field_id": "customfield_10352",
      "field_name": "Acceptance Criteria_gxp",
      "field_type": "textarea",
      "required": true,
      "description": "GXP acceptance criteria"
    },
    "story_points": {
      "field_id": "customfield_10060",
      "field_name": "Story Points",
      "field_type": "number",
      "required": false
    }
  }
}

Advanced Discovery Techniques

Discovering Required Fields

Some fields are required by project configuration or workflow rules. To discover these:

1. Attempt to create without the field - The error message often reveals required fields 2. Check project settings - Use jira_get_all_projects and examine field configurations 3. Inspect existing issues - Use jira_get_issue with fields=*all to see all populated fields

Discovering Field Value Constraints

For select, multiselect, or option fields, you need to know valid values:

Method 1: Inspect existing issues

# Get issue with all fields
jira_get_issue(issue_key="PROJ-123", fields="*all")

# Look for the custom field in response
# Example: "customfield_11077": {"value": "Platform Team"}

Method 2: Trial and error with descriptive errors

• JIRA often returns error messages listing valid options when you provide an invalid value

Method 3: Admin access

• If you have admin access, check field configuration in JIRA admin panel for allowed values

Handling Multi-Project Schemas

Different projects may use different field IDs for similar concepts:

{
  "projects": {
    "PROJ-A": {
      "owning_team_field": "customfield_11077"
    },
    "PROJ-B": {
      "owning_team_field": "customfield_12034"
    }
  }
}

Best Practice: Store mappings per project, not globally.

Common Patterns

Pattern 1: GXP/Compliance Fields

Regulated industries often have custom fields for compliance:

• Acceptance Criteria (GXP)
• Risk Assessment (GXP)
• Validation Status
• Quality Gate

Discovery: Search for keywords like "gxp", "compliance", "validation", "risk", "acceptance"

Pattern 2: Agile/Scrum Fields

Agile teams add custom fields:

• Story Points (often customfield_10060 or customfield_10016)
• Sprint (often customfield_10020)
• Epic Link (often customfield_10014)

Discovery: Search for "story", "sprint", "epic"

Pattern 3: Team/Ownership Fields

Organizations add team tracking:

• Owning Team / Responsible Team
• Technical Lead
• Product Owner

Discovery: Search for "team", "owner", "lead", "responsible"

Automation Strategy

1. Build a Field Cache

{
  "last_updated": "2025-01-15T10:00:00Z",
  "fields": [
    {
      "id": "customfield_11077",
      "name": "Owning Team",
      "type": "select",
      "projects": ["PROJ-A", "PROJ-B"]
    }
  ]
}

Refresh the cache periodically (e.g., weekly) or when field discovery fails.

2. Create Field Accessor Functions

def get_field_id(field_name, project_key):
    """Get custom field ID by name and project."""
    cache = load_field_cache()
    for field in cache['fields']:
        if field['name'] == field_name and project_key in field['projects']:
            return field['id']
    # Fallback: search fields API
    return search_and_cache_field(field_name, project_key)

3. Validate Before Creation

def validate_custom_fields(project_key, fields):
    """Ensure all custom fields exist and have correct format."""
    for field_name, value in fields.items():
        field_id = get_field_id(field_name, project_key)
        field_type = get_field_type(field_id)
        validate_value_format(value, field_type)

Error Recovery

When field discovery or usage fails:

Error: "Field 'customfield_XXXXX' cannot be set"

• Cause: Field doesn't exist, wrong project, or wrong issue type
• Solution: Re-run field search, check project/issue type constraints

Error: "Field value is not valid"

• Cause: Incorrect value format for field type
• Solution: Check schema type, verify value format matches expected type

Error: "Field is required"

• Cause: Missing required custom field
• Solution: Search for required fields, add to field mappings

Best Practices Summary

1. Search First: Always use jira_search_fields before assuming field IDs 2. Document Mappings: Store field ID mappings in project configuration files 3. Test Thoroughly: Create test issues to verify field IDs and value formats 4. Cache Strategically: Build field caches to reduce API calls 5. Project-Specific: Don't assume field IDs are the same across projects 6. Type-Aware: Respect field types when formatting values 7. Error-Friendly: Expect field discovery to fail, have fallback strategies 8. Version Control: Check field mappings into version control for team sharing

Comprehensive Guide to JIRA Query Language (JQL)

This guide provides a complete reference for using JIRA Query Language (JQL) to search and filter issues in JIRA. JQL is a powerful query language that allows you to create precise searches to find exactly the issues you need.

Table of Contents

1. Basic Syntax and Structure 2. Common Fields 3. Operators 4. Functions 5. Date and Time Queries 6. Historical Search Operators 7. Text Search 8. Working with Sprints 9. Working with Epics 10. Custom Fields 11. Time Tracking Queries 12. Comments and Descriptions 13. Watchers and Voters 14. Advanced Queries 15. Common Use Cases 16. Best Practices 17. Common Pitfalls

Basic Syntax and Structure

A JQL query consists of three main components:

field operator value

• Field: The aspect of the issue you want to search (e.g., status, assignee, project)
• Operator: How to compare the field to the value (e.g., =, !=, >, <)
• Value: What you're searching for (e.g., "Open", currentUser(), "My Project")

Combining Conditions

Use keywords to combine multiple conditions:

• AND: Both conditions must be true
• OR: Either condition must be true
• NOT: Negates a condition

Examples:

project = "DEV" AND status = "In Progress"
assignee = currentUser() OR reporter = currentUser()
project = "DEV" AND NOT status = "Closed"

Precedence and Parentheses

Use parentheses to control order of evaluation:

project = "DEV" AND (status = "Open" OR status = "In Progress")

Common Fields

Standard Fields

Agile Fields

Time Tracking Fields

Operators

Equality Operators

Comparison Operators

List Operators

Text Operators

Historical Operators

Functions

User Functions

Date/Time Functions

Date/Time Function Modifiers

You can add offsets to date functions:

startOfDay("+1d")      # Tomorrow at 00:00
startOfWeek("-1w")     # Start of last week
startOfMonth("+2M")    # Start of month, 2 months from now

Sprint Functions (Agile)

Subquery Functions

Date and Time Queries

Absolute Dates

Use ISO format (YYYY-MM-DD) or full datetime:

created >= "2025-01-01"
updated >= "2025-01-21 14:30"

Relative Dates

Use shorthand notation for relative time periods:

Examples:

# Issues created in the last 7 days
created >= -7d

# Issues updated in the last 2 weeks
updated >= -2w

# Issues created this week
created >= startOfWeek() AND created <= endOfWeek()

# Issues created today
created >= startOfDay()

# Issues due in the next 3 days
due >= now() AND due <= 3d

# Issues created between specific dates
created >= "2025-01-01" AND created <= "2025-01-31"

Historical Search Operators

Historical operators let you search based on past values of fields.

WAS Operator

Find issues that had a specific value at any point:

# Issues that were once "In Progress"
status WAS "In Progress"

# Issues that were assigned to a specific user
assignee WAS "john.doe"

WAS IN Operator

Find issues that had any of several values:

# Issues that were in any of these statuses
status WAS IN ("On Hold", "Blocked")

WAS NOT Operators

Find issues that never had a specific value:

# Issues never assigned to a user
assignee WAS NOT "john.doe"

# Issues never in specific statuses
status WAS NOT IN ("Cancelled", "Rejected")

CHANGED Operator

Find issues where a field changed, with optional predicates:

Basic change:

status CHANGED
priority CHANGED

Change with time constraints:

# Status changed in the last week
status CHANGED AFTER -7d

# Priority changed before a date
priority CHANGED BEFORE "2025-01-01"

# Status changed during a period
status CHANGED DURING ("2025-01-01", "2025-01-31")

# Status changed on a specific date
status CHANGED ON "2025-01-21"

Change by user:

# Status changed by a specific user
status CHANGED BY "john.doe"

# Assignee changed by current user
assignee CHANGED BY currentUser()

Change from/to specific values:

# Status changed from Open to In Progress
status CHANGED FROM "Open" TO "In Progress"

# Priority changed from Low
priority CHANGED FROM "Low"

# Status changed to Closed
status CHANGED TO "Closed"

Combined predicates:

# Status changed to In Progress by current user in last week
status CHANGED TO "In Progress" BY currentUser() AFTER -7d

Text Search

Contains Operator (~)

Search for text within fields:

# Summary contains "error"
summary ~ "error"

# Description contains "database"
description ~ "database"

# Environment contains "production"
environment ~ "production"

Does Not Contain Operator (!~)

Exclude issues containing text:

# Summary does not contain "test"
summary !~ "test"

# Description does not contain "legacy"
description !~ "legacy"

Wildcards

Use * for wildcard matching:

# Summary starts with "API"
summary ~ "API*"

# Summary ends with "error"
summary ~ "*error"

# Summary contains word starting with "auth"
summary ~ "auth*"

Exact Phrase Matching

Use quotes for exact phrases:

# Exact phrase in summary
summary ~ "\"login failed\""

# Multiple word search
description ~ "\"database connection timeout\""

Case Sensitivity

Text searches are case-insensitive by default:

summary ~ "error"  # Matches "Error", "ERROR", "error"

Working with Sprints

Current/Active Sprints

Find issues in currently active sprints:

sprint IN openSprints()

# For a specific board
sprint IN openSprints() AND project = "DEV"

Past Sprints

Find issues in completed sprints:

sprint IN closedSprints()

# Issues from the last completed sprint
sprint IN closedSprints() ORDER BY sprint DESC

Future Sprints

Find issues in planned sprints:

sprint IN futureSprints()

Specific Sprint

Find issues in a named sprint:

sprint = "Sprint 23"

# Partial sprint name match
sprint ~ "Sprint 2*"

Issues Not in Any Sprint

Find backlog issues not assigned to a sprint:

sprint IS EMPTY

# Backlog for a specific project
project = "DEV" AND sprint IS EMPTY

Issues in Multiple Sprint States

Combine sprint queries:

# Issues in active or future sprints
sprint IN (openSprints(), futureSprints())

# Issues not in closed sprints
sprint NOT IN closedSprints()

Sprint-Specific Examples

# Unfinished issues from closed sprints
sprint IN closedSprints() AND status != "Done"

# High priority items in current sprint
sprint IN openSprints() AND priority = "High"

# Bugs in active sprint
sprint IN openSprints() AND type = "Bug"

# Stories not estimated in backlog
project = "DEV" AND sprint IS EMPTY AND type = "Story" AND originalEstimate IS EMPTY

Working with Epics

All Issues in an Epic

Find all issues linked to a specific epic:

epicLink = "PROJ-123"

# Or using parent
parent = "PROJ-123"

Issues in Multiple Epics

epicLink IN ("PROJ-123", "PROJ-456")

Orphaned Issues

Find issues not linked to any epic:

epicLink IS EMPTY AND type != "Epic"

# Orphaned stories in a project
project = "DEV" AND type = "Story" AND epicLink IS EMPTY

Epic-Specific Queries

# All epics in a project
project = "DEV" AND type = "Epic"

# Epics without children
type = "Epic" AND issueFunction NOT IN hasLinks("is parent of")

# Open issues in a specific epic
epicLink = "PROJ-123" AND status != "Done"

# Count issues by epic (use GROUP BY in UI)
project = "DEV" AND epicLink IS NOT EMPTY

Epic Progress

# Completed issues in epic
epicLink = "PROJ-123" AND status = "Done"

# Remaining work in epic
epicLink = "PROJ-123" AND status != "Done"

# Blocked issues in epic
epicLink = "PROJ-123" AND status = "Blocked"

Custom Fields

Finding Custom Field Names

Custom fields use the format cf[XXXXX] where XXXXX is the field ID.

To find custom field IDs: 1. Use JIRA's field configuration UI 2. Inspect the field in the browser developer tools 3. Use the JIRA REST API

Querying Custom Fields

# Custom field equals value
cf[10010] = "Value"

# Custom field contains text
cf[10010] ~ "search term"

# Custom field is empty
cf[10010] IS EMPTY

# Custom field in list
cf[10010] IN ("Option1", "Option2")

Common Custom Field Examples

# Story points (common Agile field)
cf[10016] >= 8

# Epic name
cf[10011] ~ "Phase 1"

# Sprint (if custom field)
cf[10020] = "Sprint 5"

# Team field
cf[10030] = "Backend Team"

# Environment (if custom)
cf[10040] IN ("Production", "Staging")

Time Tracking Queries

Original Estimate

# Issues estimated at 8 hours or more
originalEstimate >= 8h

# Issues estimated between 4 and 8 hours
originalEstimate >= 4h AND originalEstimate <= 8h

# Unestimated issues
originalEstimate IS EMPTY

# Stories with no estimate
type = "Story" AND originalEstimate IS EMPTY

Remaining Estimate

# Issues with remaining work
remainingEstimate > 0

# Issues with more than 8 hours remaining
remainingEstimate > 8h

# No remaining estimate
remainingEstimate IS EMPTY

Time Spent

# Issues with logged time
timeSpent > 0

# Issues with more than 4 hours logged
timeSpent >= 4h

# Issues with no time logged
timeSpent IS EMPTY OR timeSpent = 0

Combined Time Tracking

# Over-estimated issues (time spent exceeds original estimate)
timeSpent > originalEstimate

# Issues with remaining work
remainingEstimate > 0 AND status != "Done"

# Completed issues with time tracking
status = "Done" AND timeSpent > 0

# Issues nearing estimate (90% or more)
timeSpent >= originalEstimate * 0.9 AND status != "Done"

Time Format Examples

Time can be specified in various units:

• m - minutes
• h - hours
• d - days (8 hours)
• w - weeks (40 hours)

originalEstimate = 30m    # 30 minutes
originalEstimate = 2h     # 2 hours
originalEstimate = 1d     # 1 day (8 hours)
originalEstimate = 2w     # 2 weeks (80 hours)

Comments and Descriptions

Searching Comments

Find issues with comments containing specific text:

# Comment contains text
comment ~ "approved"

# Comment does not contain text
comment !~ "rejected"

# Comment by specific user (requires plugin)
comment ~ "john.doe: approved"

Searching Descriptions

# Description contains text
description ~ "database migration"

# Description does not contain text
description !~ "deprecated"

# Empty description
description IS EMPTY

# Has description
description IS NOT EMPTY

Combined Text Search

# Text in summary, description, or comments
text ~ "critical issue"

# Text search excluding certain terms
text ~ "login" AND text !~ "test"

Watchers and Voters

Watchers

Find issues watched by specific users:

# Watched by current user
watcher = currentUser()

# Watched by specific user
watcher = "john.doe"

# Has watchers
watchers IS NOT EMPTY

# No watchers
watchers IS EMPTY

Voters

Find issues voted on by users:

# Voted by current user
voter = currentUser()

# Voted by specific user
voter = "jane.smith"

# Has votes
votes > 0

# More than 5 votes
votes > 5

# No votes
votes = 0

Combined Watcher/Voter Queries

# Issues you're watching or assigned to
watcher = currentUser() OR assignee = currentUser()

# Popular issues (many watchers and votes)
watchers > 10 AND votes > 5

# Issues with engagement
(watchers > 0 OR votes > 0) AND status = "Open"

Advanced Queries

Ordering Results

Use ORDER BY to sort results:

project = "DEV" ORDER BY created DESC

# Multiple sort fields
project = "DEV" ORDER BY priority DESC, created ASC

# Available sort directions: ASC (ascending), DESC (descending)

Common Sort Fields

ORDER BY created DESC           # Newest first
ORDER BY updated DESC           # Recently updated first
ORDER BY priority DESC          # Highest priority first
ORDER BY due ASC                # Earliest due date first
ORDER BY status ASC             # Alphabetical by status
ORDER BY assignee ASC           # Alphabetical by assignee
ORDER BY votes DESC             # Most voted first
ORDER BY watchers DESC          # Most watched first

Subqueries with Functions

# Issues updated by user in last 5 days
issuekey IN updatedBy("john.doe", "-5d")

# Issues linked to a specific issue
issuekey IN linkedIssues("PROJ-123")

# Issues linked with specific link type
issuekey IN linkedIssues("PROJ-123", "blocks")

Complex Boolean Logic

# Parentheses for precedence
project = "DEV" AND (status = "Open" OR status = "Reopened") AND priority IN ("High", "Critical")

# Multiple OR conditions
(assignee = currentUser() OR reporter = currentUser() OR watcher = currentUser())

# Negation with NOT
project = "DEV" AND NOT (status = "Closed" OR status = "Resolved")

Field Value Lists

# Status in multiple values
status IN ("To Do", "In Progress", "In Review")

# Priority not in list
priority NOT IN ("Low", "Lowest")

# Type in list
type IN ("Bug", "Incident", "Problem")

Common Use Cases

Personal Queries

# All my open issues
assignee = currentUser() AND status NOT IN ("Done", "Closed")

# Issues I reported
reporter = currentUser()

# Issues I'm watching
watcher = currentUser()

# Issues I'm involved in (assigned, reported, or watching)
assignee = currentUser() OR reporter = currentUser() OR watcher = currentUser()

# My issues updated today
assignee = currentUser() AND updated >= startOfDay()

Team Queries

# Team's open issues
project = "DEV" AND assignee IN membersOf("dev-team") AND status != "Done"

# Unassigned issues in project
project = "DEV" AND assignee IS EMPTY

# Issues waiting for review
project = "DEV" AND status = "In Review"

# Blocked issues
project = "DEV" AND status = "Blocked"

Sprint Queries

# Current sprint scope
sprint IN openSprints() AND project = "DEV"

# Current sprint bugs
sprint IN openSprints() AND type = "Bug"

# Unfinished sprint work
sprint IN openSprints() AND status != "Done"

# Sprint carryover (incomplete from closed sprints)
sprint IN closedSprints() AND status != "Done"

Overdue and Due Soon

# Overdue issues
due < now() AND status NOT IN ("Done", "Closed")

# Due today
due >= startOfDay() AND due <= endOfDay()

# Due this week
due >= startOfWeek() AND due <= endOfWeek()

# Due in next 3 days
due >= now() AND due <= 3d AND status != "Done"

Recently Updated

# Updated today
updated >= startOfDay()

# Updated in last 7 days
updated >= -7d

# Updated in last 24 hours
updated >= -24h

# Updated this week
updated >= startOfWeek()

Quality and Bugs

# Open bugs
type = "Bug" AND status NOT IN ("Done", "Closed")

# Critical bugs
type = "Bug" AND priority = "Critical"

# Bugs in production
type = "Bug" AND environment ~ "production"

# Unresolved bugs assigned to me
type = "Bug" AND assignee = currentUser() AND status != "Done"

# Recently reported bugs
type = "Bug" AND created >= -7d

Epic and Story Management

# All epics
type = "Epic"

# Stories without epic
type = "Story" AND epicLink IS EMPTY

# Incomplete stories in epic
epicLink = "PROJ-123" AND status != "Done"

# Unestimated stories
type = "Story" AND originalEstimate IS EMPTY

Component-Based

# Issues in specific component
component = "Frontend"

# Issues in multiple components
component IN ("Frontend", "API")

# Issues without component
component IS EMPTY

Label-Based

# Issues with specific label
labels = "urgent"

# Issues with multiple labels (AND)
labels = "urgent" AND labels = "customer-facing"

# Issues with any of multiple labels (OR)
labels IN ("urgent", "critical", "blocker")

# Issues without labels
labels IS EMPTY

Version/Release Queries

# Issues in specific fix version
fixVersion = "2.0.0"

# Issues affecting specific version
affectedVersion = "1.5.0"

# Issues without fix version
fixVersion IS EMPTY

# Issues released
fixVersion IS NOT EMPTY AND status = "Done"

Best Practices

1. Start Simple and Build Up

Begin with basic queries and add complexity gradually:

# Start: Find all bugs
type = "Bug"

# Add: Only open bugs
type = "Bug" AND status = "Open"

# Add: Only high priority open bugs
type = "Bug" AND status = "Open" AND priority = "High"

# Add: Only recent high priority open bugs
type = "Bug" AND status = "Open" AND priority = "High" AND created >= -7d

2. Use Parentheses for Clarity

Make complex logic explicit:

# Unclear precedence
project = "DEV" AND status = "Open" OR status = "Reopened" AND priority = "High"

# Clear precedence
project = "DEV" AND (status = "Open" OR status = "Reopened") AND priority = "High"

3. Use IN for Multiple Values

Cleaner than multiple OR conditions:

# Verbose
status = "Open" OR status = "In Progress" OR status = "Reopened"

# Cleaner
status IN ("Open", "In Progress", "Reopened")

4. Leverage Auto-Complete

JIRA's query editor provides auto-complete suggestions. Use it to:

• Discover available fields
• Find correct field values
• Learn function syntax
• Avoid typos

5. Save Frequently Used Queries

Save common queries as filters for quick access and sharing.

6. Use Relative Dates

Prefer relative dates for dynamic queries:

# Static - requires manual updates
created >= "2025-01-01"

# Dynamic - always shows last 7 days
created >= -7d

7. Consider Performance

For large JIRA instances:

• Limit searches to specific projects when possible
• Use indexed fields (status, priority, assignee)
• Avoid overly broad text searches
• Use time ranges to limit result sets

8. Test Queries Incrementally

Build and test queries step by step: 1. Start with basic criteria 2. Verify results 3. Add additional filters 4. Re-verify results 5. Repeat until complete

9. Document Complex Queries

Add comments to saved filters explaining the query logic:

Filter Name: Sprint Carryover Issues
Description: Incomplete work from closed sprints needing attention
JQL: sprint IN closedSprints() AND status != "Done" ORDER BY sprint DESC, priority DESC

10. Use Functions for Dynamic Queries

Prefer functions over hardcoded values:

# Hardcoded
assignee = "john.doe"

# Dynamic
assignee = currentUser()

Common Pitfalls

1. Case Sensitivity in Field Names

Problem: Field names are case-sensitive.

# Wrong
Project = "DEV"
Status = "Open"

# Correct
project = "DEV"
status = "Open"

2. Incorrect Quote Usage

Problem: Mixing single and double quotes or using wrong quotes.

# Wrong
project = 'DEV'
status = "Open"

# Correct - use double quotes consistently
project = "DEV"
status = "Open"

3. Missing Parentheses in Complex Queries

Problem: Boolean logic without parentheses can produce unexpected results.

# Unclear - may not work as intended
project = "DEV" AND status = "Open" OR priority = "High"

# Clear - explicitly states intent
project = "DEV" AND (status = "Open" OR priority = "High")

4. Using = with Multi-Value Fields

Problem: Some fields can have multiple values (labels, components).

# May not work as expected
labels = "urgent"

# Better - explicitly check for inclusion
labels IN ("urgent")

# Or use contains for partial match
labels ~ "urgent"

5. Forgetting IS EMPTY vs = null

Problem: Using wrong syntax for null/empty checks.

# Wrong
assignee = null
assignee = ""

# Correct
assignee IS EMPTY
assignee IS NOT EMPTY

6. Incorrect Date Formats

Problem: Using wrong date format.

# Wrong
created >= "01/21/2025"
created >= "21-Jan-2025"

# Correct
created >= "2025-01-21"
created >= "2025-01-21 14:30"

7. Not Accounting for Field Changes

Problem: Fields change over time (status, assignee, etc.). Use historical operators when needed.

# Only shows current status
status = "In Progress"

# Shows if status was ever "In Progress"
status WAS "In Progress"

8. Overly Broad Text Searches

Problem: Text searches can be slow and return too many results.

# Too broad - very slow
text ~ "the"

# More specific - faster and more relevant
summary ~ "login error" OR description ~ "login error"

9. Ignoring Field Data Types

Problem: Treating all fields the same way.

# Wrong - priority is not numeric
priority > 3

# Correct - use priority names
priority = "High"
priority IN ("High", "Highest")

10. Not Using ORDER BY

Problem: Results in random or unhelpful order.

# No specific order
assignee = currentUser() AND status = "Open"

# Ordered by priority and creation date
assignee = currentUser() AND status = "Open" ORDER BY priority DESC, created ASC

11. Hardcoding User Names

Problem: Queries with hardcoded usernames don't work for other users.

# Hardcoded
assignee = "john.doe"

# Dynamic - works for any user
assignee = currentUser()

12. Forgetting Sprint States

Problem: Not considering sprint state when querying sprints.

# May return closed sprints
sprint IS NOT EMPTY

# More specific - only active sprints
sprint IN openSprints()

13. Assuming Field Names

Problem: Custom field names vary by instance.

# May not exist in your instance
"Story Points" = 8

# Better - use field ID or check field name
cf[10016] = 8

14. Not Handling Special Characters

Problem: Field values or names with special characters need quoting.

# Wrong if project key has special chars
project = DEV-API

# Correct
project = "DEV-API"

# Wrong if status has spaces
status = In Progress

# Correct
status = "In Progress"

15. Inefficient Negation

Problem: Using NOT inefficiently.

# Less efficient
NOT status = "Closed"

# More efficient
status != "Closed"

# Even better for multiple exclusions
status NOT IN ("Closed", "Done", "Resolved")

Quick Reference Card

Basic Structure

field operator value
field1 = value1 AND field2 = value2
field1 = value1 OR field2 = value2
(field1 = value1 OR field2 = value2) AND field3 = value3

Common Patterns

# My open work
assignee = currentUser() AND status NOT IN ("Done", "Closed")

# Recent updates
updated >= -7d ORDER BY updated DESC

# Overdue items
due < now() AND status != "Done"

# Current sprint
sprint IN openSprints()

# Specific epic
epicLink = "PROJ-123"

# No assignee
assignee IS EMPTY

# Has comments
comment ~ "*"

# Text search
summary ~ "keyword" OR description ~ "keyword"

Date Shortcuts

-1d    # Yesterday
-1w    # Last week
-1M    # Last month
now()  # Current time
startOfDay()
startOfWeek()
startOfMonth()

Useful Functions

currentUser()
membersOf("group-name")
openSprints()
closedSprints()

---

Additional Resources

• JIRA Documentation: Official Atlassian JQL reference
• JQL Cheat Sheet: Quick reference guide available from Atlassian
• JIRA Query Builder: Use JIRA's built-in simple/advanced search interface
• Browser Extensions: Consider JQL helper extensions for syntax highlighting

Conclusion

JQL is a powerful tool for managing and analyzing JIRA issues. Start with simple queries and gradually build complexity as needed. Remember to:

1. Use auto-complete to discover fields and values 2. Test queries incrementally 3. Save frequently used queries as filters 4. Use relative dates and dynamic functions for flexible queries 5. Order results for better usability 6. Consider performance for large instances

With practice, JQL becomes an essential tool for efficiently managing your work in JIRA.