# Jira Jql

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-magnus919-agent-skills-jira-jql`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [magnus919](https://agentstack.voostack.com/s/magnus919)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [magnus919](https://github.com/magnus919)
- **Source:** https://github.com/magnus919/agent-skills/tree/main/jira-jql

## Install

```sh
agentstack add skill-magnus919-agent-skills-jira-jql
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Jira Query Language (JQL) — Expert Reference

JQL is Atlassian's structured query language for searching Jira issues (now called "work items"). Every clause is **Field + Operator + Value**, chained with keywords.

Use this skill when:
- The user asks for help writing or debugging a JQL query
- They need to find issues across projects, sprints, versions, components
- They want to use history operators (WAS, CHANGED) for trend/sprint analysis
- Performance optimization or saved filter design is needed
- They're building automation rules, REST API calls, or dashboard gadgets with JQL

---

## 1. Core Syntax

```
field OPERATOR value [AND|OR field OPERATOR value ...] [ORDER BY field [ASC|DESC]]
```

### Operators

| Operator | Meaning | Example |
|----------|---------|---------|
| `=`, `!=` | Equals, not equals | `assignee = currentUser()` |
| `>`, `=`, `= -7d` |
| `IN`, `NOT IN` | Set membership | `status IN ("To Do", "In Progress")` |
| `IS`, `IS NOT` | Null check — only with `EMPTY` or `NULL` | `assignee IS EMPTY` |
| `~`, `!~` | Contains (text search) | `summary ~ "login*"` |
| `WAS`, `WAS NOT` | Historical value | `assignee WAS "jsmith"` |
| `WAS IN`, `WAS NOT IN` | Historical set | `fixVersion WAS IN ("Sprint 1", "Sprint 2")` |
| `CHANGED` | Field transition | `status CHANGED FROM "Open" TO "Done"` |

### Keywords

| Keyword | Purpose |
|---------|---------|
| `AND` | Both conditions must be true (binds tighter than OR) |
| `OR` | At least one condition must be true |
| `NOT` | Negates a clause |
| `ORDER BY` | Sorting — add `ASC` or `DESC` (default ASC) |
| `EMPTY` / `NULL` | Used with `IS` / `IS NOT` |

### Precedence

**AND binds tighter than OR.** `A OR B AND C` = `A OR (B AND C)`. Always parenthesize OR groups:

```jql
-- Correct
(project = A OR project = B) AND status = Open

-- Wrong — reads as project = A OR (project = B AND status = Open)
project = A OR project = B AND status = Open
```

---

## 2. Available Fields (System)

Common indexed fields that JQL accepts:

`project`, `issuetype`, `status`, `assignee`, `reporter`, `creator`, `priority`, `resolution`, `resolutiondate`, `created`, `updated`, `duedate`, `fixVersion`, `affectedVersion`, `component`, `labels`, `sprint`, `votes`, `watchers`, `workRatio`, `parentEpic`, `issueLinkType`, `statusCategory`

Custom fields work by name — quote if they contain spaces: `"Story Points"`.

**Pro tip:** Prefer IDs over names for project/sprint/version when possible — names change, IDs (`project = 1001`) don't.

---

## 3. Functions (Complete Catalog)

### Date/Time Relative Functions

All accept optional increment strings in `(+/-)nn(y|M|w|d|h|m)` format. Default unit matches the function's natural period.

| Function | Default Unit | Example |
|----------|-------------|---------|
| `startOfDay()` / `endOfDay()` | `d` | `created > startOfDay("-1")` = yesterday |
| `startOfWeek()` / `endOfWeek()` | `w` | `due  startOfMonth("-1")` = start of last month |
| `startOfYear()` / `endOfYear()` | `y` | `resolutiondate > startOfYear()` |
| `now()` | — | Current timestamp |
| `currentLogin()` | — | When session began |
| `lastLogin()` | — | Previous login |

### User Functions

| Function | Fields | Operators | Behavior |
|----------|--------|-----------|----------|
| `currentUser()` | Assignee, Reporter, Voter, Watcher, Creator + custom User | `=`, `!=` | Your identity |
| `membersOf("group")` | Assignee, Reporter, Voter, Watcher, Creator | `IN`, `NOT IN`, `WAS IN`, `WAS NOT IN` | Group members. For teams: `membersOf(id:)` |
| `componentsLeadByUser(user)` | Component | `IN`, `NOT IN` | Omit user = current user |
| `spacesLeadByUser(user)` | Project (Space) | `IN`, `NOT IN` | Omit user = current user |
| `spacesWhereUserHasPermission(p)` | Project | `IN`, `NOT IN` | e.g. `"Edit work items"` |
| `spacesWhereUserHasRole(role)` | Project | `IN`, `NOT IN` | e.g. `"Administrators"` |

### Sprint/Version Functions

| Function | Fields | Behavior |
|----------|--------|----------|
| `openSprints()` | Sprint | Active, not yet completed |
| `closedSprints()` | Sprint | Completed sprints |
| `earliestUnreleasedVersion(project)` | AffectedVersion, FixVersion, custom Version | Earliest unreleased in release order |
| `latestReleasedVersion(project)` | Same | Most recently released version |
| `releasedVersions(project)` | Same | All released. Omit project for all |
| `unreleasedVersions(project)` | Same | All unreleased. Omit project for all |

### Issue Functions

| Function | Syntax | Description |
|----------|--------|-------------|
| `linkedIssues(key, linkType?)` | `issue in linkedIssues("ABC-44")` | Link type optional — e.g. `"is blocked by"` |
| `parentEpic` (field) | `parentEpic = DEMO-123` | Stories/subtasks in an epic |
| `issueHistory()` | `issue in issueHistory()` | Recently viewed |
| `votedWorkItems()` | `issue in votedWorkItems()` | You voted on these |
| `watchedWorkItems()` | `issue in watchedWorkItems()` | You watch these |
| `updatedBy(user, from?, to?)` | `issue in updatedBy(jsmith, "-8d")` | Updated by user. Rounds = -7d                                          -- Last 7 days
duedate >= startOfWeek() AND duedate = startOfDay(-3M) AND resolutiondate  startOfMonth("-1")                            -- Since start of last month
updated = startOfMonth()`

### Scope-Sort Pattern

Start broad, narrow iteratively:

```jql
-- Step 1: all open issues
project = PWC AND status = open

-- Step 2: narrow by sprint
project = PWC AND status = open AND fixVersion = "Current Sprint"

-- Step 3: carried-over issues only
project = PWC AND status = open AND fixVersion = "Current Sprint" AND fixVersion WAS "Last Sprint"

-- Step 4: sort by priority then assignee
... ORDER BY priority, assignee
```

---

## 7. Role-Based Ready Queries

### Developers

```jql
-- My unresolved issues by priority
assignee = currentUser() AND resolution = Unresolved ORDER BY priority DESC

-- Bugs I reported
reporter = currentUser() AND status != Done

-- My completed work this week
resolution = Fixed AND resolutiondate >= -7d AND assignee = currentUser()

-- Where I'm mentioned in comments
comment ~ currentUser()
```

### Scrum Masters

```jql
-- Unassigned in active sprint
sprint IN openSprints() AND assignee IS EMPTY

-- Stale tickets
status NOT IN (Closed, Done) AND updated = startOfMonth() AND duedate = -180d
```

---

## 8. Gotchas & Known Limitations

- **Standard JQL has no aggregation** — no COUNT, SUM, AVG. Use dashboard gadgets or marketplace apps.
- **Can't check linked issue status** — `issueLinkType = "is blocked by"` finds links but can't check if the blocker is resolved. Needs ScriptRunner.
- **No recursive hierarchy traversal** — epics+stories+subtasks need separate queries.
- **`updatedBy()` rounds < 1 day up to 1 day** — `updatedBy(jsmith, "-1h")` becomes 1 day.
- **`membersOf()` does NOT support project roles** — only groups and teams.
- **`IS EMPTY` works for fields that exist** — can't find issues where a field was *never* created.
- **Atlassian is renaming "issue" to "work item"** — old terms (`project`, `issue`, `fixVersion`) still work; no migration needed.
- **Starting a text search with `*` is very expensive** — put wildcards after the first few chars.

### Marketplace Extensions for Advanced Needs

| Extension | What It Adds |
|-----------|-------------|
| JQL Tricks Plugin | 50+ extra functions |
| JQL Search Extensions (Cloud) | Find comments, attachments, subtasks, epics |
| JQL Booster Pack (Server/DC) | 15+ user-related functions |
| ScriptRunner (Adaptavist) | Custom Groovy JQL functions — most powerful |

---

## 9. JQL in REST API

Query via Jira REST API v3:

```bash
curl -u email:token \
  "https://your-domain.atlassian.net/rest/api/3/search?jql=project=PWC+AND+status=Open&fields=summary,assignee"
```

Returns structured JSON. Use `jql` parameter, URL-encode when needed. Also supports `startAt`, `maxResults`, `fields`, `expand` params.

---

## 10. Edge Cases & Troubleshooting

**Query is valid but slow:** Check for leading wildcards, unindexed custom fields, or missing project filter.

**Query returns 0 results unexpectedly:** Verify field names haven't changed (esp. custom fields), check for case sensitivity in values (depends on Jira config), and ensure you're in the right project scope.

**"Filter not found" when using `filter =`:** The user doesn't have permission to that saved filter.

**`CHANGED` returns nothing:** Ensure the field actually has tracking enabled. Some custom fields don't log history.

**Jira says "Field 'X' does not exist":** The field name is wrong, disabled for this project, or requires a marketplace app.

---

## Key Reference URLs

- **Official JQL Functions:** https://support.atlassian.com/jira-software-cloud/docs/jql-functions/
- **JQL Operators:** https://support.atlassian.com/jira-software-cloud/docs/jql-operators/
- **JQL Fields:** https://support.atlassian.com/jira-software-cloud/docs/jql-fields/
- **JQL Keywords:** https://support.atlassian.com/jira-software-cloud/docs/jql-keywords/
- **JQL Performance KB:** https://confluence.atlassian.com/jirakb/understanding-jql-performance-720416549.html
- **Free Atlassian University Intro to JQL:** https://www.youtube.com/watch?v=BcHKXSiOHqw

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [magnus919](https://github.com/magnus919)
- **Source:** [magnus919/agent-skills](https://github.com/magnus919/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-magnus919-agent-skills-jira-jql
- Seller: https://agentstack.voostack.com/s/magnus919
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.