jira-communication
Use Cautionnpx machina-cli add skill netresearch/jira-skill/jira-communication --openclawJira Communication
CLI scripts for Jira operations using uv run. All scripts support --help, --json, --quiet, --debug.
Paths are relative to skills/jira-communication/. Run from there or prefix accordingly.
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:
# 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
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 syntaxreferences/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.
Multi-Profile Support
When ~/.jira/profiles.json exists, multiple Jira instances are supported.
Profile resolution (automatic, priority order):
--env-file PATH→ legacy single-file behavior--profile NAMEflag → use named profile directly- Full Jira URL in input → match host to profile
- Issue key (e.g., WEB-1381) → match project prefix to profile
.jira-profilefile in working directory → use named profile- Default profile from profiles.json
- Fallback to
~/.env.jira
When triggered by URL → extract host → match profile automatically:
# User mentions https://jira.meine-krankenkasse.de/browse/WEB-1381
# Profile "mkk" is automatically resolved from URL host match
uv run scripts/core/jira-issue.py get WEB-1381
When triggered by issue key only → check project mapping automatically:
# WEB is mapped to "mkk" profile → automatically resolved
uv run scripts/core/jira-issue.py get WEB-1381
If ambiguous → ask user which profile to use.
Profile management:
uv run scripts/core/jira-setup.py --profile mkk # Create profile
uv run scripts/core/jira-validate.py --profile mkk --verbose # Validate profile
uv run scripts/core/jira-validate.py --all-profiles # Validate all
uv run scripts/core/jira-setup.py --migrate # Migrate .env.jira
Source
git clone https://github.com/netresearch/jira-skill/blob/main/skills/jira-communication/SKILL.mdView on GitHub Overview
Jira-communication provides CLI scripts to search, create, update, transition, comment, log work, download attachments, and manage sprints, boards, issue links, fields, or users. It auto-triggers on Jira URLs and issue keys to streamline workflows.
How This Skill Works
Scripts are run with uv run and support --help, --json, --quiet, --debug. They authenticate via profiles and environment credentials, resolving the correct Jira instance automatically from a URL or an issue key, enabling direct issue operations.
When to Use It
- To quickly fetch an issue by key (e.g., PROJ-123) or from a Jira URL.
- To create, update, or comment on an issue, or to log work against it.
- To perform a JQL-based search to locate issues you care about.
- To download attachments from a specific issue.
- To list or manage Jira boards, sprints, issue links, fields, or users.
Quick Start
- Step 1: uv run scripts/core/jira-setup.py to configure credentials.
- Step 2: uv run scripts/core/jira-validate.py --verbose to verify the connection.
- Step 3: uv run scripts/core/jira-issue.py get PROJ-123 to fetch an issue.
Best Practices
- Prefer --json output for machine-friendly results.
- Validate the connection with jira-validate before performing mutations.
- Use --profile to pin to the intended Jira instance and avoid cross-instance surprises.
- Follow the global flags-before-subcommand order as documented.
- Test disruptive actions with --dry-run when supported (e.g., transitions).
Example Use Cases
- uv run scripts/core/jira-issue.py get PROJ-123
- uv run scripts/core/jira-search.py query 'assignee = currentUser()'
- 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
- uv run scripts/core/jira-attachment.py download PROJ-123 myfile.pdf
