alivirgo 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
- Prefer fewer statuses; map real handoffs, not aspirational bureaucracy.
- Name custom fields carefully; avoid duplicates (
Start DatevsStart date). - Automation: guard with conditions; never create infinite ping-pong transitions.
- JQL should be selective enough for humans and APIs (watch result caps).
- 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