Imported from atlassian/twg-cli (skills/twg-jira/SKILL.md). Install upstream with npx skills add atlassian/twg-cli --skill twg-jira. Copyright stays with the author.

twg-jira

Use with the root twg skill when Jira is the source of truth or a Jira mutation is required. This skill owns Jira semantics and safety; command grammar comes from live twg help.

CLI launcher fallback

Run twg <command>. On shell command not found, use $HOME/.local/bin/twg (macOS/Linux) / $env:LOCALAPPDATA\Programs\twg\bin\twg.exe (PowerShell), then tell user to add that directory to PATH. Do not treat auth or command errors as PATH failures.

Use When

• A Jira key, issue URL, project key, board, sprint, filter, or dashboard is the primary anchor.
• The user asks to create, update, transition, comment on, link, watch, or delete Jira work.
• The user asks to find or review duplicate Jira workitems.
• Required or custom fields must be discovered and populated.
• A workflow skill needs authoritative Jira fields or status.

Do not load this skill merely because Jira appears as one supporting artifact inside a cross-product answer.

First Route

Run one focused twg help describe "<exact path>" before an unfamiliar or consequential mutation.

Jira Semantics

• "Issue" and "workitem" refer to the same Jira object in user language.
• Jira projects/spaces are not Atlas projects. Use Jira for issue containers, schemes, boards, versions, components, filters, and dashboards.
• JSM requests have an underlying Jira workitem, but approvals, portals, queues, request types, and SLAs belong to JSM.
• Search results are candidate anchors; use the native workitem read for final fields and status. Plain get avoids supplemental hydration; add --comments and/or --remote-links, or --full for all fields plus both.
• For "what should I pick next," query actual open Jira work or the requested board backlog. Do not rank from broad activity alone.
• Read a set of workitems in one call: jira workitem get, jira workitem bulk-get, and context jira workitem all accept every key at once. Never loop get over a key list. When the fields are queryable, use jira workitem query --jql <jql> --fields <fields> and skip hydration.

Safe Reads And Writes

• Resolve the site and workitem key before mutation.
• Read current state before update, transition, link, comment, or delete.
• Discover create/update field metadata before supplying required or custom fields.
• Use returned customfield_* IDs rather than display names in writes.
• Discover available transitions instead of guessing a transition name or ID.
  • Run twg jira workitem transition --id <KEY> --site <SITE> -o json without --transition-id to discover available transitions and their required screen fields.
  • Select one and use its requirements to gather field values before calling with --transition-id.
  • Treat required fields as user-decision inputs. If the user did not supply a required value, do not infer or choose an allowed value; ask the user before transitioning. This includes Resolution: a request to cancel does not imply Won't Do, Declined, Duplicate, or another Resolution.
  • This discovery call is read-only and does not transition the workitem.
• Keep global Jira field administration separate from workitem field values.
• Use typed workitem artifact links to add Jira remote links to PRs, repos, deployments, builds, branches, commits, Loom videos, or meetings. These are not Jira Software devinfo/provider writes.
• Verify mutations with a native read and report the resulting key and URL.

Handoffs

• Load twg-context-discovery for dependencies, related documents, or implementation links; twg-responsibility-routing for owners, experts, authority, or escalation.
• Load twg-status-rollups for project, sprint, team, or leadership synthesis.
• Load twg-engineering-work when the Jira anchor must be traced to PRs or repositories.
• Load twg-operational-health for incident, PIR, or reliability workflows.

References

• references/workitems.md - workitem reads, writes, comments, and links
• references/fields-and-transitions.md - metadata-first fields and workflow changes
• references/querying.md - JQL and board/backlog selection
• references/duplicates.md - prompt driven duplicate detection and review
• references/rich-content.md - descriptions, comments, and mentions
• references/administration.md - Jira configuration versus workitem data