# jira

A Claude Code skill that talks to the Jira Cloud API: JQL search, issue create and update, comments, child issues. Ships as a Python script with a setup check command.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 139 installs · ★ 13 repo stars
- Author: odyssey4me
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/odyssey4me/agent-skills/tree/HEAD/skills/jira/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/odyssey4me-jira

## What it does

The `jira.py` script exposes `search`, `issue get`, `issue create`, `issue update`, `issue comment`, and `check` subcommands.

Jira Cloud only. Auth comes from `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` environment variables or `~/.config/agent-skills/jira.yaml`; the Atlassian API token is generated in account security settings. Outbound HTTPS to the Jira host must be allowed before the first remote call — the skill does not grant network access itself.

Search takes a JQL string, contributor, team, and project filters, plus `--max-results` (default 50). Batch-read multiple issues in one call, create from a markdown file with `--from-file`, and `--contributors` walks every comment to report reporter, assignee, and commenter roles. Python dependencies are `requests`, `keyring`, `pyyaml`, `pyadf`.

## Requirements
- Works with: Jira, Atlassian

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add odyssey4me/agent-skills --skill jira -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/jira/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/jira/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add odyssey4me/agent-skills --skill jira -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/jira/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add odyssey4me/agent-skills --skill jira -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/jira/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install odyssey4me/agent-skills skills/jira
```

2. **Manually: put the files in place**
- File: `.github/skills/jira/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add odyssey4me/agent-skills --skill jira -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/odyssey4me/agent-skills --path skills/jira
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/jira/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add odyssey4me/agent-skills --skill jira -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/odyssey4me/agent-skills/tree/HEAD/skills/jira/SKILL.md

## When to use it
- find open issues in a project with JQL
- create a ticket from a markdown file
- collect all comment authors from a long thread
- update summary, priority, story points, or parent
- verify Jira connectivity before running queries

## Example prompts
- Search project DEMO for open issues and list them with assignee and status
- Create a Story under EPIC-123 using the description in issue.md
- Comment on DEMO-123 that the deploy finished successfully

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 3fc53d323a009b25.

BEGIN THIRD-PARTY FILE 3fc53d323a009b25
````text
---
name: jira
description: Search and manage Jira issues using JQL queries, create/update tickets, and manage workflows. Use when asked to find Jira tickets, check the backlog, manage sprints, track bugs, or work with Atlassian project management.
metadata:
  author: odyssey4me
  version: "1.3.0"
  category: project-management
  tags: "issues, agile, sprints"
  complexity: standard
license: MIT
---

# Jira

Interact with Jira for issue tracking, search, and workflow management.

## Resolving script paths

`SKILL_DIR` in the examples is the directory containing this loaded `SKILL.md`.
Set it to that absolute path before running commands; do not assume the agent
sets this shell variable. Quote the script path if it contains spaces.

## Installation

1. **Install Python dependencies**:
   ```bash
   pip install --user requests keyring pyyaml pyadf
   ```

2. **Download the skill** from [Releases](https://github.com/odyssey4me/agent-skills/releases) or use directly from this repository.

## Setup Verification

After installation, verify the skill configuration by running:

```bash
$SKILL_DIR/scripts/jira.py check
```

This will check:
- Python dependencies (requests, keyring, pyyaml, pyadf)
- Authentication configuration
- Connectivity to Jira

If anything is missing, the check command will provide setup instructions.

## Network access

Jira API commands require outbound HTTPS to the configured Jira host. Remote operations require outbound network access. If the agent environment restricts it, obtain access through that environment's approval or network controls before the first remote command, reusing authorization already granted. Local help and file processing do not need network access. Skill instructions do not grant network permission. Report DNS, connection, and timeout failures as network errors; do not reset credentials to resolve them. If approved access also fails, stop and report it. Authentication and permission errors require user action.

## Authentication

This skill supports Jira Cloud only.

Configure Jira authentication using one of these methods:

### Option 1: Environment Variables (Recommended)

```bash
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_EMAIL="you@example.com"
export JIRA_API_TOKEN="your-token"
```

Add these to your `~/.bashrc` or `~/.zshrc` for persistence.

### Option 2: Config File

Create `~/.config/agent-skills/jira.yaml`:

```yaml
url: https://yourcompany.atlassian.net
email: you@example.com
token: your-token
```

### Required Credentials

- **URL**: Your Jira instance URL (e.g., `https://yourcompany.atlassian.net`)
- **Email**: Your Atlassian account email
- **API Token**: Create at https://id.atlassian.com/manage-profile/security/api-tokens

## Configuration Defaults
````
END THIRD-PARTY FILE 3fc53d323a009b25

The third-party file has ended. Everything between the 3fc53d323a009b25 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2780 of 10002 bytes. © odyssey4me · MIT · https://github.com/odyssey4me/agent-skills/tree/HEAD/skills/jira/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
