home / skills / questnova502 / claude-skills-sync / jira-communication

jira-communication skill

unsafe

/skills/jira-integration/skills/jira-communication

This skill lets you manage Jira issues and workflows from Python CLI, including search, get, create, transition, comments, and attachments.

npx playbooks add skill questnova502/claude-skills-sync --skill jira-communication

Review the files below or copy the command above to add this skill to your agents.

Files (22)

SKILL.md

3.1 KB

---
name: jira-communication
description: >
  Jira API operations via Python CLI scripts. AUTOMATICALLY TRIGGER when user
  mentions Jira URLs (https://jira.*/browse/*, https://*.atlassian.net/browse/*),
  issue keys (PROJ-123), or asks about Jira issues. Use when Claude needs to:
  (1) Search issues with JQL queries, (2) Get or update issue details,
  (3) Create new issues, (4) Transition issue status (e.g., "To Do" → "Done"),
  (5) Add comments, (6) Log work time (worklogs), (7) List sprints and sprint issues,
  (8) List boards and board issues, (9) Create or list issue links,
  (10) Discover available Jira fields, (11) Get user profile information,
  (12) Download attachments from issues.
  If authentication fails, offer interactive credential setup via jira-setup.py.
  Supports both Jira Cloud and Server/Data Center with automatic auth detection.
---

# Jira Communication

CLI scripts for Jira operations using `uv run`. All scripts support `--help`, `--json`, `--quiet`, `--debug`.

## Auto-Trigger

Trigger when user mentions:
- **Jira URLs**: `https://jira.*/browse/*`, `https://*.atlassian.net/browse/*`
- **Issue keys**: `PROJ-123`, `NRS-4167`

When triggered by URL → extract issue key → run `jira-issue.py get PROJ-123`

## Auth Failure Handling

When auth fails, offer: `uv run scripts/core/jira-setup.py` (interactive credential setup)

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/core/jira-setup.py` | Interactive credential config |
| `scripts/core/jira-validate.py` | Verify connection |
| `scripts/core/jira-issue.py` | Get/update issue details |
| `scripts/core/jira-search.py` | Search with JQL |
| `scripts/core/jira-worklog.py` | Time tracking |
| `scripts/core/jira-attachment.py` | Download attachments |
| `scripts/workflow/jira-create.py` | Create issues |
| `scripts/workflow/jira-transition.py` | Change status |
| `scripts/workflow/jira-comment.py` | Add comments |
| `scripts/workflow/jira-sprint.py` | List sprints |
| `scripts/workflow/jira-board.py` | List boards |
| `scripts/utility/jira-user.py` | User info |
| `scripts/utility/jira-fields.py` | Search fields |
| `scripts/utility/jira-link.py` | Issue links |

## Critical: Flag Ordering

Global flags **MUST** come **before** subcommand:
```bash
# Correct:  uv run scripts/core/jira-issue.py --json get PROJ-123
# Wrong:    uv run scripts/core/jira-issue.py get PROJ-123 --json
```

## Quick Examples

```bash
uv run scripts/core/jira-validate.py --verbose
uv run scripts/core/jira-search.py query "assignee = currentUser()"
uv run scripts/core/jira-issue.py get PROJ-123
uv run scripts/core/jira-worklog.py add PROJ-123 2h --comment "Work done"
uv run scripts/workflow/jira-transition.py do PROJ-123 "In Progress" --dry-run
```

## Related Skills

**jira-syntax**: For descriptions/comments. Jira uses wiki markup, NOT Markdown.

## References

- `references/jql-quick-reference.md` - JQL syntax
- `references/troubleshooting.md` - Setup and auth issues

## Authentication

**Cloud**: `JIRA_URL` + `JIRA_USERNAME` + `JIRA_API_TOKEN`
**Server/DC**: `JIRA_URL` + `JIRA_PERSONAL_TOKEN`

Config via `~/.env.jira` or env vars. Run `jira-validate.py --verbose` to verify.

Overview

This skill provides a set of Python CLI scripts for performing Jira API operations from the command line. It automatically triggers when Jira issue keys or Jira browse URLs are mentioned, extracting the key and running the appropriate command. Use it to search, view, create, transition, comment, log work, manage sprints/boards, discover fields, get user info, and download attachments for both Jira Cloud and Server/Data Center.

How this skill works

When a Jira URL or issue key is detected, the skill extracts the issue key and invokes the matching CLI script to run the requested Jira API call. Scripts accept global flags (--json, --quiet, --debug, --verbose) which must appear before the subcommand. Authentication is automatically detected for Cloud vs Server/DC; if credentials are missing or invalid the skill offers an interactive setup flow to configure env vars or a local credential file.

When to use it

User posts a Jira URL (https://…/browse/PROJ-123) or mentions an issue key (PROJ-123).
You need to search issues using JQL queries or run saved filters.
Get, update, or create issues and inspect issue fields and attachments.
Transition an issue between statuses or run dry-run transitions.
Add comments, create or list links, or log time via worklogs.
List boards, sprints, sprint issues, or get Jira user profiles and available fields.

Best practices

Place global flags before the subcommand (e.g., uv run ... --json get PROJ-123).
Run the interactive credential setup if auth fails (sets JIRA_URL and token vars).
Use --json for machine-friendly output and --quiet for minimal logs in scripts.
Run validate with verbose mode to confirm connection before bulk operations.
Use dry-run where available before executing transitions or destructive actions.

Example use cases

Extract PROJ-123 from a message and fetch issue details with the get command.
Search for all issues assigned to current user using a JQL query.
Create a new issue from a CLI workflow script and attach initial comments.
Transition an issue from "To Do" to "Done" with a dry-run first.
Add a worklog entry (e.g., 2h) with a comment after completing work.
Download attachments from an issue for local review or archival.

FAQ

What happens if authentication fails?

The skill offers an interactive setup flow to configure credentials and environment variables, and recommends running the validate command to verify the connection.

Why did my flags get ignored?

Global flags must appear before the subcommand. Place flags like --json or --debug immediately after the script and before the action and arguments.