name	jira
description	Manages JIRA issues, projects, and workflows using Atlassian MCP. Use when asked to "create JIRA ticket", "search JIRA", "update JIRA issue", "transition issue", "sprint planning", or "epic management".

JIRA Management Skill

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

Overview
Prerequisites
Skill Workflow
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

Get boards: mcp__atlassian__jira_get_agile_boards
- Filter by: board_name, project_key, board_type (scrum/kanban)
Get board issues: mcp__atlassian__jira_get_board_issues
- Requires board_id and jql filter

Working with Sprints

Get sprints: mcp__atlassian__jira_get_sprints_from_board
- Filter by state: "active", "future", "closed"
Get sprint issues: mcp__atlassian__jira_get_sprint_issues
- Returns all issues in specified sprint
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"
}

Update sprint: mcp__atlassian__jira_update_sprint

Working with Epics

Find epics: Use JQL: issuetype = Epic AND project = PROJ
Link to epic: mcp__atlassian__jira_link_to_epic
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

Get versions: mcp__atlassian__jira_get_project_versions
Create version: mcp__atlassian__jira_create_version
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

Install Skill

SKILL.md