jira

Query Jira with JQL, manage issue fields and workflows, and plan scoped REST updates for project operations.

SKILL.md

GitHub

Jira Project Tracking AI Skill Guide

Overview & Engine Architecture

Jira tracks work items (issues) through workflows with statuses, transitions, and fields. Boards and sprints organize delivery; JQL queries filter issues. Automation rules can react to events. Agents write precise JQL, avoid automation loops, keep workflows simple, and use the REST API carefully with least-privilege tokens.

Projects -> Issues (fields)
         -> Workflows (statuses/transitions)
         -> Boards / sprints
         -> Automation / REST API

When to use this skill

  • Building filters, boards, and saved JQL
  • Designing lightweight workflows
  • Bulk-updating issues via API during migrations
  • Reviewing noisy automation rules

Operational directives

  1. Prefer fewer statuses; map real handoffs, not aspirational bureaucracy.
  2. Name custom fields carefully; avoid duplicates (Start Date vs Start date).
  3. Automation: guard with conditions; never create infinite ping-pong transitions.
  4. JQL should be selective enough for humans and APIs (watch result caps).
  5. Store API tokens as secrets; scope to needed permissions.

Useful JQL

project = APP AND status = "In Progress" AND assignee = currentUser()
ORDER BY updated DESC

project = APP AND sprint in openSprints() AND type in (Bug, Story)

project = APP AND resolution is EMPTY AND updated <= -14d

REST sketch

# List issues via search (Cloud APIs evolve - verify current endpoint)
curl -s -u email:token \
  -H "Accept: application/json" \
  "$JIRA_BASE/rest/api/3/search?jql=project%3DAPP"

Workflow hygiene

Smell Better approach
15+ statuses Collapse to Todo / Doing / Done + optional Blocked
Required fields on every transition Require only at the gate that needs them
Automation comments on every edit Filter to meaningful events
Everyone is admin Role-based scheme permissions

Best practices

  • Link issues to PRs/commits with clear keys in branch names (APP-123-...).
  • Use components or labels consistently; document the taxonomy.
  • Separate bug vs story workflows only if states truly differ.
  • Archive stale projects instead of leaving eternal noise.

Limitations

  • Jira Cloud vs Data Center APIs and permissions differ.
  • Advanced Roadmaps / Plans features depend on license.
  • Marketplace apps add fields/behaviors this skill cannot fully cover.

Related skills

  • @linear - lighter issue tracking alternative
  • @confluence - long-form docs linked from epics
  • @github-actions - CI status next to issue keys