/jira-integration

name: jira-integration
description: Use this skill when retrieving Jira tickets, analyzing requirements, updating ticket status, adding comments, or transitioning issues. Provides Jira API patterns via MCP or direct REST calls.
metadata:
  origin: ECC

Jira Integration Skill

Retrieve, analyze, and update Jira tickets directly from your AI coding workflow. Supports both **MCP-based** (recommended) and **direct REST API** approaches.

When to Activate

• Fetching a Jira ticket to understand requirements
• Extracting testable acceptance criteria from a ticket
• Adding progress comments to a Jira issue
• Transitioning a ticket status (To Do → In Progress → Done)
• Linking merge requests or branches to a Jira issue
• Searching for issues by JQL query

Prerequisites

Option A: MCP Server (Recommended)

Install the `mcp-atlassian` MCP server. This exposes Jira tools directly to your AI agent.

**Requirements:**

• Python 3.10+
• `uvx` (from `uv`), installed via your package manager or the official `uv` installation documentation

**Add to your MCP config** (e.g., `~/.claude.json` → `mcpServers`):

{
  "jira": {
    "command": "uvx",
    "args": ["mcp-atlassian==0.21.0"],
    "env": {
      "JIRA_URL": "https://YOUR_ORG.atlassian.net",
      "JIRA_EMAIL": "your.email@example.com",
      "JIRA_API_TOKEN": "your-api-token"
    },
    "description": "Jira issue tracking — search, create, update, comment, transition"
  }
}

> **Security:** Never hardcode secrets. Prefer setting `JIRA_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` in your system environment (or a secrets manager). Only use the MCP `env` block for local, uncommitted config files.

**To get 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 — store it in your environment, never in source code

Option B: Direct REST API

If MCP is not available, use the Jira REST API v3 directly via `curl` or a helper script.

**Required environment variables:**

| Variable | Description | |----------|-------------| | `JIRA_URL` | Your Jira instance URL (e.g., `https://yourorg.atlassian.net`) | | `JIRA_EMAIL` | Your Atlassian account email | | `JIRA_API_TOKEN` | API token from id.atlassian.com |

Store these in your shell environment, secrets manager, or an untracked local env file. Do not commit them to the repo.

For direct `curl` examples, keep credentials out of command-line arguments by passing the Jira user config on stdin:

jira_curl() {
  printf 'user = "%s:%s"\n' "$JIRA_EMAIL" "$JIRA_API_TOKEN" |
    curl -s -K - "$@"
}

MCP Tools Reference

When the `mcp-atlassian` MCP server is configured, these tools are available:

| Tool | Purpose | Example | |------|---------|---------| | `jira_search` | JQL queries | `project = PROJ AND status = "In Progress"` | | `jira_get_issue` | Fetch full issue details by key | `PROJ-1234` | | `jira_create_issue` | Create issues (Task, Bug, Story, Epic) | New bug report | | `jira_update_issue` | Update fields (summary, description, assignee) | Change assignee | | `jira_transition_issue` | Change status | Move to "In Review" | | `jira_add_comment` | Add comments | Progress update | | `jira_get_sprint_issues` | List issues in a sprint | Active sprint review | | `jira_create_issue_link` | Link issues (Blocks, Relates to) | Dependency tracking | | `jira_get_issue_development_info` | See linked PRs, branches, commits | Dev context |

> **Tip:** Always call `jira_get_transitions` before transitioning — transition IDs vary per project workflow.

Direct REST API Reference

Fetch a Ticket

jira_curl \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{
    key: .key,
    summary: .fields.summary,
    status: .fields.status.name,
    priority: .fields.priority.name,
    type: .fields.issuetype.name,
    assignee: .fields.assignee.displayName,
    labels: .fields.labels,
    description: .fields.description
  }'

Fetch Comments

jira_curl \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | {
    author: .author.displayName,
    created: .created[:10],
    body: .body
  }'

Add a Comment

jira_curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "version": 1,
      "type": "doc",
      "content": [{
        "type": "paragraph",
        "content": [{"type": "text", "text": "Your comment here"}]
      }]
    }
  }' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment"

Transition a Ticket

# 1. Get available transitions
jira_curl \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}'

# 2. Execute transition (replace TRANSITION_ID)
jira_curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"transition": {"id": "TRANSITION_ID"}}' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions"

Search with JQL

jira_curl -G \
  --data-urlencode "jql=project = PROJ AND status = 'In Progress'" \
  "$JIRA_URL/rest/api/3/search"

Analyzing a Ticket

When retrieving a ticket for development or test automation, extract:

1. Testable Requirements

• **Functional requirements** — What the feature does
• **Acceptance criteria** — Conditions that must be met
• **Testable behaviors** — Specific actions and expected outcomes
• **User roles** — Who uses this feature and their permissions
• **Data requirements** — What data is needed
• **Integration points** — APIs, services, or systems involved

2. Test Types Needed

• **Unit tests** — Individual functions and utilities
• **Integration tests** — API endpoints and service interactions
• **E2E tests** — User-facing UI flows
• **API tests** — Endpoint contracts and error handling

3. Edge Cases & Error Scenarios

• Invalid inputs (empty, too long, special characters)
• Unauthorized access

-