Purpose

Use this skill when you need to interact with Jira: reading tickets, creating new work items, updating existing ones, searching with JQL, transitioning status, assigning, commenting, or browsing projects. acli jira provides full Jira Cloud management from the CLI.

When to use what

acli jira workitem view : View a specific ticket by key. Use to read ticket details, description, status, assignee, etc.
acli jira workitem search : Find tickets using JQL queries. Use for any search, filtering, or listing of work items.
acli jira workitem create : Create a new ticket. Use when the user wants to file a bug, task, story, or epic.
acli jira workitem edit : Modify an existing ticket's summary, description, labels, type, or assignee.
acli jira workitem transition : Move a ticket to a new status (e.g., "In Progress", "Done").
acli jira workitem assign : Change or remove a ticket's assignee.
acli jira workitem comment create : Add a comment to a ticket.
acli jira workitem comment list : Read comments on a ticket.
acli jira project list : List available projects. Use to discover project keys.
acli jira project view : View details of a specific project.
acli jira sprint list-workitems : List tickets in a sprint (requires --sprint and --board IDs).
acli jira board search : Find boards by name or keyword.

Core concepts

Always use --json on read commands (view , search , comment list , project list , etc.) to get machine-readable output.
Always use --yes on mutation commands (edit , transition , assign ) to skip interactive confirmation prompts that would hang in a non-interactive shell.
JQL (Jira Query Language) is used for searching. Pass it via --jql "..." .
@me is a shorthand for the authenticated user (works in --assignee ).
Labels are comma-separated: --label "bug,backend,urgent" .
Work item types use Jira issue types: Task , Bug , Story , Epic , Sub-task , etc. Pass via --type .
Keys are project-prefixed IDs like PROJ-123 . Multiple keys are comma-separated: --key "PROJ-1,PROJ-2" .

Recommended workflow

Discover projects: acli jira project list --json to find available project keys.
Search for tickets: acli jira workitem search --jql "project = PROJ AND ..." --json to find relevant work items.
View a ticket: acli jira workitem view PROJ-123 --json to read full details.
Create/edit/transition as needed using the commands below.

Common JQL patterns

All open tickets in a project

--jql "project = PROJ AND status != Done"

Tickets assigned to me

--jql "assignee = currentUser()"

Bugs created this week

--jql "project = PROJ AND type = Bug AND created >= startOfWeek()"

Tickets with a specific label

--jql "project = PROJ AND labels = backend"

Search by summary text

--jql "project = PROJ AND summary ~ "search term""

High priority open items

--jql "project = PROJ AND priority in (High, Highest) AND status != Done"

View specific fields only

acli jira workitem view PROJ-123 --fields "summary,status,assignee,labels,comment" --json

Search for tickets

Search with JQL, get JSON output

acli jira workitem search --jql "project = PROJ AND status = 'In Progress'" --json

Search with specific fields and a result limit

acli jira workitem search --jql "project = PROJ AND assignee = currentUser()"
--fields "key,summary,status,priority,labels" --limit 20 --json

Get count of matching tickets

acli jira workitem search --jql "project = PROJ AND type = Bug" --count

Create a ticket

Basic creation

acli jira workitem create
--project "PROJ"
--type "Task"
--summary "Implement feature X"
--description "Detailed description here"
--label "backend,feature"
--assignee "@me"
--json

Create a bug with a parent (sub-task)

acli jira workitem create
--project "PROJ"
--type "Bug"
--summary "Fix login timeout"
--description "Users report timeout after 30s on the login page"
--label "bug,auth"
--parent "PROJ-100"
--json

Create with description from a file

acli jira workitem create
--project "PROJ"
--type "Story"
--summary "User onboarding flow"
--description-file description.txt
--json

Edit a ticket

Edit summary and labels

acli jira workitem edit --key "PROJ-123"
--summary "Updated summary"
--labels "backend,urgent"
--yes --json

Change assignee

acli jira workitem edit --key "PROJ-123"
--assignee "user@company.com"
--yes --json

Remove labels

acli jira workitem edit --key "PROJ-123"
--remove-labels "stale"
--yes --json

Transition a ticket

Move to In Progress

acli jira workitem transition --key "PROJ-123" --status "In Progress" --yes --json

Mark as Done

acli jira workitem transition --key "PROJ-123" --status "Done" --yes --json

Transition multiple tickets

acli jira workitem transition --key "PROJ-1,PROJ-2,PROJ-3" --status "Done" --yes --json

Assign a ticket

Assign to self

acli jira workitem assign --key "PROJ-123" --assignee "@me" --yes --json

Assign to someone else

acli jira workitem assign --key "PROJ-123" --assignee "user@company.com" --yes --json

Remove assignee

acli jira workitem assign --key "PROJ-123" --remove-assignee --yes --json

Comments

Add a comment

acli jira workitem comment create --key "PROJ-123" --body "This is ready for review"

List comments

acli jira workitem comment list --key "PROJ-123" --json

Projects

List all projects

acli jira project list --json

View a specific project

acli jira project view --key "PROJ" --json

List recently viewed projects

acli jira project list --recent --json

Sprints and boards

Find a board

acli jira board search --name "My Team" --json

List sprints on a board

acli jira board list-sprints --id 42 --json

List tickets in a sprint

acli jira sprint list-workitems --sprint 101 --board 42 --json

Important tips

When creating tickets, always ask the user for the project key if not already known. Use acli jira project list --json to discover available projects.
When creating tickets, infer appropriate labels from context (e.g., the area of the codebase, the type of work). Labels help with discoverability.
Prefer --json output for all read operations so you can parse and summarize results for the user.
Use --yes on all write operations to avoid interactive prompts.
For large result sets, use --limit to cap results or --paginate to fetch everything.
Status names for transitions are project-specific. If a transition fails, the error message will list valid statuses.
To set custom fields (not exposed as CLI flags), use --from-json with additionalAttributes . Generate a template with acli jira workitem create --generate-json .

Board-specific conventions

For project-specific board conventions (required fields, custom field mappings, labels, templates), read the file ~/.config/opencode/skills/acli-jira/boards.md if it exists. It contains board-specific conventions needed before creating or managing tickets on known boards.

This allows board conventions to be kept private (not checked into version control) while the core skill remains public.

acli-jira

Safety Notice

Copy this and send it to your AI assistant to learn