jira-communication
Use when handling Jira issues, sprints, boards, links, fields, worklogs, attachments, or users, or on any Jira intent without a key ("create/find a ticket", "pick a project"). Auto-triggers on Jira URLs and issue keys (PROJ-123). Also use when MCP Atlassian tools fail or are unav
Install
npx skills add https://github.com/netresearch/jira-skill/tree/main/skills/jira-communication
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install netresearch-jira-skill@llmmart
git clone https://github.com/netresearch/jira-skill.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole netresearch/jira-skill collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Jira Communication
CLI scripts via uv run, all supporting --help, --json, --quiet, --debug.
Auto-Trigger
On Jira URL or issue key (PROJ-123), pick by intent — each is one call:
| Intent | Tool |
|---|---|
| triage / work on ticket | jira-issue.py work KEY |
| start QA review | jira-issue.py qa KEY |
| QA-fail follow-up | jira-issue.py qa-fail KEY |
| field-only lookup | jira-issue.py get KEY --fields ... |
| change status | jira-issue.py act KEY → jira-transition.py do |
| audit / sibling discovery / "am I reviewing my own work?" | jira-qa-gather.py KEY |
Auth issues → jira-setup.py. Anti-pattern: get + comment list — use the matching verb.
work flags a ticket you have not taken: when it is not assigned to you, or its status says nobody works on it (To Do category, a review status such as QA, or resolved), a !! CLAIM KEY notice on stderr (claim in --json) lists the commands — jira-issue.py update KEY --assignee me, then the start or reopen transition from jira-transition.py list KEY. Run them before your first comment, measurement or edit. jira-comment.py add warns once before posting when the ticket is neither yours nor in a working status; it still posts.
Scripts
Under ${CLAUDE_SKILL_DIR}/scripts/{core,workflow,utility}/.
Core: jira-issue.py, jira-search.py, jira-worklog.py, jira-attachment.py, jira-setup.py, jira-validate.py
Workflow: jira-create.py, jira-transition.py, jira-comment.py, jira-move.py, jira-sprint.py, jira-board.py, jira-version.py, tempo-account.py
Utility: jira-user.py, jira-fields.py, jira-link.py, jira-weblink.py, jira-worklog-query.py, jira-watchers.py, jira-qa-gather.py
Execution Style
Run directly. Scripts report ✓/✗. Destructive ops: --dry-run. Global flags before subcommand: jira-issue.py --json get PROJ-123.
Every write ends with the ticket's state
After a successful write, these commands print the ticket's state to stderr: jira-comment.py add/edit, jira-transition.py do/path, jira-issue.py update, jira-worklog.py add, jira-weblink.py add, jira-link.py create (FROM_KEY, which is --target in the named form), jira-attachment.py add and jira-create.py issue:
── PROJ-123 · Task · Open · resolution: – · assignee: unassigned
time: logged 15m / estimate – / remaining – · labels: –
(!) ticket is "Open" while you work on it: claim it (assign + start work)
Read the (!) lines and act on them before reporting the work done. They appear when the ticket is Open or Backlog while you write to it, unassigned while In Progress, assigned to someone else while you write to it, already done while you write to it, done without a resolution, carries a resolution while not done, or has more time logged than estimated. An unassigned ticket in a review status such as QA gets no hint: it waits for the team pool by design. After a transition or a create only the resolution and time checks run, because the status and assignee are what the command just set.
With --json the same facts arrive as a ticket_state field in the output object, beside the keys it already had: key, status, status_category, issuetype, resolution, assignee, assignee_is_you, time_spent_seconds, original_estimate_seconds, remaining_estimate_seconds, labels and hints, the last being the (!) lines as strings. Read ticket_state.hints as you would the (!) lines. jira-attachment.py add --json prints a list, so its state goes to stderr as text instead. --quiet prints no state.
The state costs one extra read per write (jira-comment.py add reads once more before posting, for its claim warning) and never fails the command: a lookup error prints one line, or becomes "ticket_state": {"key": …, "error": "<type>"} in JSON. JIRA_TICKET_STATE=0 turns it off everywhere, together with the warning jira-comment.py add prints before posting; the work claim notice stays. logged is Jira's own time tracking: time booked elsewhere shows only once it is synced into a Jira worklog.
Posting wiki markup rewrites and checks it first
Every --comment and --description option that writes wiki markup runs three gates before the write, all on by default, because text that renders wrong is silent — the API returns 2xx either way. That is all seven: jira-comment.py add/edit, jira-transition.py do --comment, jira-transition.py path --comment, jira-worklog.py add --comment, and the --description of jira-create.py issue and jira-issue.py update. A body smuggled in through --fields-json is not gated — that option writes raw fields by design. jira-version.py writes two --description fields that are NOT gated (create and update); whether Jira renders a version description as wiki markup at all is unverified, and its help string claiming it does may simply be wrong.
- Dashes that Jira would render as strikethrough are escaped.
\-prints as a plain hyphen, so the posted text reads as written; stderr names how many lines changed and shows the first five. (The one shape where the escape is visible is two macros written against each other with no space — the dash can land inside a link target. Ordinary prose does not reach it.)--no-auto-escapekeeps the markup verbatim — but on its own it does not post a deliberate-strikethrough-: the lint and the render check each still refuse the span. Use--no-auto-escape --forcefor that. - The markup and the ticket language are linted. Block tags used inline (
{code},{noformat},{quote},{panel}are block-level), unbalanced tag counts, German prose on an English-only project, and a reference to another comment by position ("the comment above", "Kommentar oben" — comment order is a per-user setting; write "the previous comment" or use a permalink) each abort the write.--forceturns the findings into warnings and posts anyway. - The text is rendered by the instance and refused if it comes back struck through. This costs one API call per post and catches what no local check can — an autolinked issue key creates a boundary that exists only on an instance where that key resolves. A resolved issue's key, which Jira draws struck through as status styling, is not reported.
--no-preflightskips it; an unreachable renderer warns once and posts anyway.
--force posts despite any of the three. The flags are spelled the same on each command. All seven also take --dry-run: the escape and the lint still run — the preview shows the text a real write would post — while the render call and the write do not. See references/comments.md for the details.
Basic Usage
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py get PROJ-123
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-search.py query "assignee = currentUser() AND status != Closed" -n 5 -f key,summary,status
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py update PROJ-123 --assignee me --priority Critical
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 "Comment text"
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 "Comment text" --no-auto-escape --force # deliberate -strikethrough-
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-transition.py do PROJ-123 "In Progress"
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-worklog.py add PROJ-123 2h --comment "Work done"
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-create.py issue PROJ "Summary" --type Task
Transitions:
listshows each transition's id and what its screen requires; pass the id todo— a name or a target status is not always unique, and an ambiguous one is refused rather than guessed. Terminal transitions: pass--resolution <value>(Done,Won't do); if rejected ("cannot be set"), retry without it —references/intent-verbs.md. Versions: readreferences/versions.mdbeforejira-version.py. Mentions: posting commands verify[~username](miss → suggestions);get/workprint usernames (references/fields-and-users.md).
Related Skills
jira-syntax: descriptions/comments use Jira wiki markup, not Markdown.
No editorializing
State what happened, not how good it is — references/no-editorializing.md.
References
references/jql-quick-reference.md,references/jql-cookbook.mdreferences/multi-profile.md—--profilereferences/troubleshooting.md— auth, 401/403references/issue-editing.md— edit, delete, clear fields,--fields-jsonreferences/creation.md— create,--parent, fields, admin-scope (project,tempo-account.py)references/comments.md— edit, delete, lint, body via-, restricted comments (--visibility)references/worklog.md—--started, ranges,--tempo-account,deletereferences/attachments.md— upload, downloadreferences/links.md— linksreferences/agile.md— sprints/boardsreferences/no-editorializing.md— no self-praisereferences/fields-and-users.md— custom field IDs, users, issue types, screen fields (jira-fields.py meta)references/watchers.md— watch, subscribe, list watchersreferences/versions.md— fix/affects versions, releases, version CRUDreferences/qa-gather.md— audit bundle (siblings, prose URLs, self-review check from changelog + worklog — not the assignee)references/intent-verbs.md—work / qa / qa-fail / act, exact transition names
Authentication
Cloud: JIRA_URL + JIRA_USERNAME + JIRA_API_TOKEN. Server/DC: JIRA_URL + JIRA_PERSONAL_TOKEN. Config via ~/.env.jira or ~/.jira/profiles.json.
Files (jira-skill)
-
evals
-
evals.json 7.6 KB
Loading…
-
-
references
-
agile.md 1.9 KB
Loading… -
attachments.md 4.7 KB
Loading… -
comments.md 14.4 KB
Loading… -
creation.md 4 KB
Loading… -
fields-and-users.md 7.7 KB
Loading… -
intent-verbs.md 13.5 KB
Loading… -
issue-editing.md 11.6 KB
Loading… -
jql-cookbook.md 8 KB
Loading… -
jql-quick-reference.md 6.3 KB
Loading… -
links.md 7.8 KB
Loading… -
multi-profile.md 3.9 KB
Loading… -
no-editorializing.md 2.3 KB
Loading… -
qa-gather.md 12.1 KB
Loading… -
troubleshooting.md 12 KB
Loading… -
versions.md 7.7 KB
Loading… -
watchers.md 3.9 KB
Loading… -
worklog.md 8.6 KB
Loading…
-
-
scripts
-
core
-
jira-attachment.py 21.2 KB
Loading… -
jira-issue.py 50.6 KB
Loading… -
jira-search.py 9.6 KB
Loading… -
jira-setup.py 20 KB
Loading… -
jira-validate.py 14.2 KB
Loading… -
jira-worklog.py 15.5 KB
Loading…
-
-
lib
-
changelog.py 8 KB
Loading… -
client.py 26.4 KB
Loading… -
config.py 15.9 KB
Loading… -
errors.py 1.8 KB
Loading… -
input.py 3.5 KB
Loading… -
jql.py 375 B
Loading… -
markup.py 33.2 KB
Loading… -
markup_cli.py 11.3 KB
Loading… -
output.py 6.9 KB
Loading… -
preview.py 10 KB
Loading… -
render.py 1.8 KB
Loading… -
ticket_state.py 13.3 KB
Loading… -
users.py 7.5 KB
Loading… -
__init__.py 742 B
Loading…
-
-
utility
-
jira-fields.py 11.7 KB
Loading… -
jira-link.py 42.9 KB
Loading… -
jira-qa-gather.py 26.3 KB
Loading… -
jira-user.py 9.3 KB
Loading… -
jira-watchers.py 9.1 KB
Loading… -
jira-weblink.py 11.2 KB
Loading… -
jira-worklog-query.py 27.4 KB
Loading…
-
-
workflow
-
jira-board.py 7 KB
Loading… -
jira-comment.py 19.2 KB
Loading… -
jira-create.py 24.3 KB
Loading… -
jira-move.py 23.5 KB
Loading… -
jira-sprint.py 8.1 KB
Loading… -
jira-transition.py 33.7 KB
Loading… -
jira-version.py 29.4 KB
Loading… -
tempo-account.py 9.1 KB
Loading…
-
-
-
AGENTS.md 2.5 KB
Loading… -
SKILL.md 10.4 KB
--- # SPDX-License-Identifier: CC-BY-SA-4.0 # SPDX-FileCopyrightText: Netresearch DTT GmbH name: jira-communication description: "Use when handling Jira issues, sprints, boards, links, fields, worklogs, attachments, or users, or on any Jira intent without a key (\"create/find a ticket\", \"pick a project\"). Auto-triggers on Jira URLs and issue keys (PROJ-123). Also use when MCP Atlassian tools fail or are unavailable for Jira Server/DC." license: "(MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.0" compatibility: "Requires python 3.11+, uv. Jira Server/DC or Cloud instance with API access." metadata: author: Netresearch DTT GmbH version: "5.2.0" repository: https://github.com/netresearch/jira-skill allowed-tools: Bash(uv run ${CLAUDE_SKILL_DIR}/scripts/*) Bash(${CLAUDE_SKILL_DIR}/scripts/*) Read Write --- # Jira Communication CLI scripts via `uv run`, all supporting `--help`, `--json`, `--quiet`, `--debug`. ## Auto-Trigger On Jira URL or issue key (PROJ-123), pick by **intent** — each is one call: | Intent | Tool | |---|---| | triage / work on ticket | `jira-issue.py work KEY` | | start QA review | `jira-issue.py qa KEY` | | QA-fail follow-up | `jira-issue.py qa-fail KEY` | | field-only lookup | `jira-issue.py get KEY --fields ...` | | change status | `jira-issue.py act KEY` → `jira-transition.py do` | | audit / sibling discovery / "am I reviewing my own work?" | `jira-qa-gather.py KEY` | Auth issues → `jira-setup.py`. **Anti-pattern:** `get` + `comment list` — use the matching verb. **`work` flags a ticket you have not taken:** when it is not assigned to you, or its status says nobody works on it (To Do category, a review status such as QA, or resolved), a `!! CLAIM KEY` notice on stderr (`claim` in `--json`) lists the commands — `jira-issue.py update KEY --assignee me`, then the start or reopen transition from `jira-transition.py list KEY`. Run them before your first comment, measurement or edit. `jira-comment.py add` warns once before posting when the ticket is neither yours nor in a working status; it still posts. ## Scripts Under `${CLAUDE_SKILL_DIR}/scripts/{core,workflow,utility}/`. **Core**: `jira-issue.py`, `jira-search.py`, `jira-worklog.py`, `jira-attachment.py`, `jira-setup.py`, `jira-validate.py` **Workflow**: `jira-create.py`, `jira-transition.py`, `jira-comment.py`, `jira-move.py`, `jira-sprint.py`, `jira-board.py`, `jira-version.py`, `tempo-account.py` **Utility**: `jira-user.py`, `jira-fields.py`, `jira-link.py`, `jira-weblink.py`, `jira-worklog-query.py`, `jira-watchers.py`, `jira-qa-gather.py` ## Execution Style Run directly. Scripts report `✓`/`✗`. Destructive ops: `--dry-run`. Global flags before subcommand: `jira-issue.py --json get PROJ-123`. ## Every write ends with the ticket's state After a successful write, these commands print the ticket's state to stderr: `jira-comment.py add`/`edit`, `jira-transition.py do`/`path`, `jira-issue.py update`, `jira-worklog.py add`, `jira-weblink.py add`, `jira-link.py create` (FROM_KEY, which is `--target` in the named form), `jira-attachment.py add` and `jira-create.py issue`: ```text ── PROJ-123 · Task · Open · resolution: – · assignee: unassigned time: logged 15m / estimate – / remaining – · labels: – (!) ticket is "Open" while you work on it: claim it (assign + start work) ``` **Read the `(!)` lines and act on them before reporting the work done.** They appear when the ticket is Open or Backlog while you write to it, unassigned while In Progress, assigned to someone else while you write to it, already done while you write to it, done without a resolution, carries a resolution while not done, or has more time logged than estimated. An unassigned ticket in a review status such as QA gets no hint: it waits for the team pool by design. After a transition or a create only the resolution and time checks run, because the status and assignee are what the command just set. With `--json` the same facts arrive as a `ticket_state` field in the output object, beside the keys it already had: `key`, `status`, `status_category`, `issuetype`, `resolution`, `assignee`, `assignee_is_you`, `time_spent_seconds`, `original_estimate_seconds`, `remaining_estimate_seconds`, `labels` and `hints`, the last being the `(!)` lines as strings. **Read `ticket_state.hints` as you would the `(!)` lines.** `jira-attachment.py add --json` prints a list, so its state goes to stderr as text instead. `--quiet` prints no state. The state costs one extra read per write (`jira-comment.py add` reads once more before posting, for its claim warning) and never fails the command: a lookup error prints one line, or becomes `"ticket_state": {"key": …, "error": "<type>"}` in JSON. `JIRA_TICKET_STATE=0` turns it off everywhere, together with the warning `jira-comment.py add` prints before posting; the `work` claim notice stays. `logged` is Jira's own time tracking: time booked elsewhere shows only once it is synced into a Jira worklog. ## Posting wiki markup rewrites and checks it first Every `--comment` and `--description` option that writes wiki markup runs three gates before the write, all on by default, because text that renders wrong is silent — the API returns 2xx either way. That is all seven: `jira-comment.py add`/`edit`, `jira-transition.py do --comment`, `jira-transition.py path --comment`, `jira-worklog.py add --comment`, and the `--description` of `jira-create.py issue` and `jira-issue.py update`. A body smuggled in through `--fields-json` is not gated — that option writes raw fields by design. `jira-version.py` writes two `--description` fields that are NOT gated (`create` and `update`); whether Jira renders a version description as wiki markup at all is unverified, and its help string claiming it does may simply be wrong. 1. **Dashes that Jira would render as strikethrough are escaped.** `\-` prints as a plain hyphen, so the posted text reads as written; stderr names how many lines changed and shows the first five. (The one shape where the escape is visible is two macros written against each other with no space — the dash can land inside a link target. Ordinary prose does not reach it.) `--no-auto-escape` keeps the markup verbatim — but on its own it does not post a deliberate `-strikethrough-`: the lint and the render check each still refuse the span. Use `--no-auto-escape --force` for that. 2. **The markup and the ticket language are linted.** Block tags used inline (`{code}`, `{noformat}`, `{quote}`, `{panel}` are block-level), unbalanced tag counts, German prose on an English-only project, and a reference to another comment by position ("the comment above", "Kommentar oben" — comment order is a per-user setting; write "the previous comment" or use a permalink) each abort the write. `--force` turns the findings into warnings and posts anyway. 3. **The text is rendered by the instance and refused if it comes back struck through.** This costs one API call per post and catches what no local check can — an autolinked issue key creates a boundary that exists only on an instance where that key resolves. A resolved issue's key, which Jira draws struck through as status styling, is not reported. `--no-preflight` skips it; an unreachable renderer warns once and posts anyway. `--force` posts despite any of the three. The flags are spelled the same on each command. All seven also take `--dry-run`: the escape and the lint still run — the preview shows the text a real write would post — while the render call and the write do not. See `references/comments.md` for the details. ## Basic Usage ```bash uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py get PROJ-123 uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-search.py query "assignee = currentUser() AND status != Closed" -n 5 -f key,summary,status uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py update PROJ-123 --assignee me --priority Critical uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 "Comment text" uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 "Comment text" --no-auto-escape --force # deliberate -strikethrough- uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-transition.py do PROJ-123 "In Progress" uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-worklog.py add PROJ-123 2h --comment "Work done" uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-create.py issue PROJ "Summary" --type Task ``` > **Transitions**: `list` shows each transition's id and what its screen requires; pass the **id** to `do` — a name or > a target status is not always unique, and an ambiguous one is refused rather than guessed. > **Terminal transitions**: pass `--resolution <value>` (`Done`, `Won't do`); if rejected ("cannot be set"), > retry without it — `references/intent-verbs.md`. **Versions**: read `references/versions.md` before `jira-version.py`. > **Mentions**: posting commands verify `[~username]` (miss → suggestions); `get`/`work` print usernames (`references/fields-and-users.md`). ## Related Skills **jira-syntax**: descriptions/comments use Jira wiki markup, not Markdown. ## No editorializing State what happened, not how good it is — `references/no-editorializing.md`. ## References - `references/jql-quick-reference.md`, `references/jql-cookbook.md` - `references/multi-profile.md` — `--profile` - `references/troubleshooting.md` — auth, 401/403 - `references/issue-editing.md` — edit, delete, clear fields, `--fields-json` - `references/creation.md` — create, `--parent`, fields, admin-scope (`project`, `tempo-account.py`) - `references/comments.md` — edit, delete, lint, body via `-`, restricted comments (`--visibility`) - `references/worklog.md` — `--started`, ranges, `--tempo-account`, `delete` - `references/attachments.md` — upload, download - `references/links.md` — links - `references/agile.md` — sprints/boards - `references/no-editorializing.md` — no self-praise - `references/fields-and-users.md` — custom field IDs, users, issue types, screen fields (`jira-fields.py meta`) - `references/watchers.md` — watch, subscribe, list watchers - `references/versions.md` — fix/affects versions, releases, version CRUD - `references/qa-gather.md` — audit bundle (siblings, prose URLs, self-review check from changelog + worklog — not the assignee) - `references/intent-verbs.md` — `work / qa / qa-fail / act`, exact transition names ## Authentication Cloud: `JIRA_URL` + `JIRA_USERNAME` + `JIRA_API_TOKEN`. Server/DC: `JIRA_URL` + `JIRA_PERSONAL_TOKEN`. Config via `~/.env.jira` or `~/.jira/profiles.json`.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.