Skip to content

netresearch/jira-skill / skills/jira-communication

jira-communication

Flagged

Use when handling Jira issues, sprints, boards, links, fields, worklogs, attachments, or users, or on any Jira intent without a key ("create/find a ticket", "pick a project"). Auto-triggers on Jira URLs and issue keys (PROJ-123). Also use when MCP Atlassian tools fail or are unavailable for Jira Server/DC.

FileKindSize
AGENTS.mdmarkdown2.5 KB
CLAUDE.mdmarkdown9 B
SKILL.mdskill md10.4 KB
evals/evals.jsonconfig7.6 KB
references/agile.mdmarkdown1.9 KB
references/attachments.mdmarkdown4.7 KB
references/comments.mdmarkdown14.4 KB
references/creation.mdmarkdown4.0 KB
references/fields-and-users.mdmarkdown7.7 KB
references/intent-verbs.mdmarkdown13.5 KB
references/issue-editing.mdmarkdown11.6 KB
references/jql-cookbook.mdmarkdown8.0 KB
references/jql-quick-reference.mdmarkdown6.3 KB
references/links.mdmarkdown7.8 KB
references/multi-profile.mdmarkdown3.9 KB
references/no-editorializing.mdmarkdown2.3 KB
references/qa-gather.mdmarkdown12.1 KB
references/troubleshooting.mdmarkdown12.0 KB
references/versions.mdmarkdown7.7 KB
references/watchers.mdmarkdown3.9 KB
references/worklog.mdmarkdown8.6 KB
scripts/core/jira-attachment.pyexecutablescript21.2 KB
scripts/core/jira-issue.pyexecutablescript50.6 KB
scripts/core/jira-search.pyexecutablescript9.6 KB
scripts/core/jira-setup.pyexecutablescript20.0 KB
scripts/core/jira-validate.pyexecutablescript14.2 KB
scripts/core/jira-worklog.pyexecutablescript15.5 KB
scripts/lib/__init__.pyscript742 B
scripts/lib/changelog.pyscript8.0 KB
scripts/lib/client.pyscript26.4 KB
scripts/lib/config.pyscript15.9 KB
scripts/lib/errors.pyscript1.8 KB
scripts/lib/input.pyscript3.5 KB
scripts/lib/jql.pyscript375 B
scripts/lib/markup.pyscript33.2 KB
scripts/lib/markup_cli.pyscript11.3 KB
scripts/lib/output.pyscript6.9 KB
scripts/lib/preview.pyscript10.0 KB
scripts/lib/render.pyscript1.8 KB
scripts/lib/ticket_state.pyscript13.3 KB
scripts/lib/users.pyscript7.5 KB
scripts/utility/jira-fields.pyexecutablescript11.7 KB
scripts/utility/jira-link.pyexecutablescript42.9 KB
scripts/utility/jira-qa-gather.pyexecutablescript26.3 KB
scripts/utility/jira-user.pyexecutablescript9.3 KB
scripts/utility/jira-watchers.pyexecutablescript9.1 KB
scripts/utility/jira-weblink.pyexecutablescript11.2 KB
scripts/utility/jira-worklog-query.pyexecutablescript27.4 KB
scripts/workflow/jira-board.pyexecutablescript7.0 KB
scripts/workflow/jira-comment.pyexecutablescript19.2 KB
scripts/workflow/jira-create.pyexecutablescript24.3 KB
scripts/workflow/jira-move.pyexecutablescript23.5 KB
scripts/workflow/jira-sprint.pyexecutablescript8.1 KB
scripts/workflow/jira-transition.pyexecutablescript33.7 KB
scripts/workflow/jira-version.pyexecutablescript29.4 KB
scripts/workflow/tempo-account.pyexecutablescript9.1 KB

references/jql-quick-reference.md

View on GitHub
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->

# JQL Quick Reference

## When to load

Load this reference whenever a JQL query goes beyond the inline SKILL.md examples — any use of `AND`/`OR` combinators, historical operators (`WAS`, `CHANGED`), functions (`currentUser()`, `startOfWeek()`), or unfamiliar field names.

Common JQL patterns for `jira-search.py query "<JQL>"`.

## Sorting (`ORDER BY`)

Two equivalent forms — pick one, never both (the script rejects mixing them):

```bash
# Embedded in the JQL string
jira-search query "project = PROJ AND status = Open ORDER BY updated DESC"

# Via the --order-by flag (repeatable for multi-key sorts)
jira-search query "project = PROJ AND status = Open" --order-by "updated DESC"
jira-search query "project = PROJ" \
    --order-by "priority DESC" --order-by "created ASC"
```

Both forms support the same sort keys (any indexed Jira field) and the
same `ASC` / `DESC` direction modifiers. The flag form is friendlier when
JQL is composed programmatically and the base query should stay untouched.

## Operators

### Comparison
| Operator | Example | Notes |
|----------|---------|-------|
| `=` | `status = "In Progress"` | Exact match |
| `!=` | `status != Done` | Not equal |
| `>` | `votes > 4` | Greater than (dates, versions, numbers) |
| `>=` | `duedate >= "2024-01-01"` | Greater than or equal |
| `<` | `priority < High` | Less than |
| `<=` | `updated <= -4w` | Less than or equal |

### Text Search
| Operator | Example | Notes |
|----------|---------|-------|
| `~` | `summary ~ "login"` | Contains (fuzzy match) |
| `!~` | `summary !~ "test"` | Does not contain |

### List & Null
| Operator | Example | Notes |
|----------|---------|-------|
| `IN` | `status IN (Open, "In Progress")` | Multiple values |
| `NOT IN` | `priority NOT IN (Low, Lowest)` | Exclude values |
| `IS EMPTY` | `assignee IS EMPTY` | Field has no value |
| `IS NOT EMPTY` | `fixVersion IS NOT EMPTY` | Field has value |

### Historical
| Operator | Example | Notes |
|----------|---------|-------|
| `WAS` | `assignee WAS "john"` | Previous value |
| `WAS IN` | `status WAS IN (Open, "To Do")` | Previous in list |
| `WAS NOT` | `status WAS NOT Done` | Was never value |
| `CHANGED` | `status CHANGED` | Value was modified |

`CHANGED` supports predicates: `FROM`, `TO`, `BY`, `DURING`, `BEFORE`, `AFTER`, `ON`
```jql
status CHANGED FROM "Open" TO "In Progress" BY currentUser() AFTER -7d
```

## Functions

### User Functions
| Function | Description |
|----------|-------------|
| `currentUser()` | Logged-in user |
| `membersOf("group")` | Members of a group |

### Date Functions
| Function | Description |
|----------|-------------|
| `now()` | Current timestamp |
| `startOfDay()` | Midnight today |
| `startOfWeek()` | Start of current week |
| `startOfMonth()` | First of current month |
| `startOfYear()` | January 1st current year |
| `endOfDay()` | End of today (23:59:59) |
| `endOfWeek()` | End of current week |
| `endOfMonth()` | Last day of current month |
| `endOfYear()` | December 31st current year |

Date offsets: `startOfDay(-1)` = yesterday, `startOfWeek(1)` = next week

### Relative Dates
| Format | Example | Description |
|--------|---------|-------------|
| `-Nd` | `-7d` | N days ago |
| `-Nw` | `-2w` | N weeks ago |
| `-Nm` | `-1m` | N months ago |
| `"YYYY-MM-DD"` | `"2024-01-15"` | Specific date |

### Sprint Functions
| Function | Description |
|----------|-------------|
| `openSprints()` | Active sprints |
| `closedSprints()` | Completed sprints |
| `futureSprints()` | Planned sprints |

### Version Functions
| Function | Description |
|----------|-------------|
| `releasedVersions()` | Released versions |
| `unreleasedVersions()` | Unreleased versions |
| `latestReleasedVersion()` | Most recent release |

## Common Queries

### By Assignment
```jql
assignee = currentUser()
assignee = "john.doe"
assignee IS EMPTY
assignee IN membersOf("developers")
```

### By Status
```jql
status = "In Progress"
status IN (Open, "To Do", "In Progress")
status != Done
status WAS "Open"
status CHANGED FROM "Open" TO "In Progress"
```

### By Date
```jql
created >= -7d
updated >= startOfWeek()
due <= endOfMonth()
resolved >= "2024-01-01"
created >= startOfMonth(-1) AND created < startOfMonth()
```

### By Sprint
```jql
sprint IN openSprints()
sprint IN closedSprints()
sprint = "Sprint 42"
sprint IS EMPTY
```

### By Text
```jql
text ~ "error message"
summary ~ "login bug"
description ~ "timeout"
comment ~ "workaround"
```

## Combining Conditions

```jql
project = PROJ AND status = Open

priority = High OR priority = Highest

project = PROJ AND (status = Open OR status = "In Progress") AND assignee = currentUser()

NOT status = Done

project = PROJ ORDER BY priority DESC, created ASC
```

## Keywords

| Keyword | Usage |
|---------|-------|
| `AND` | Both conditions must match |
| `OR` | Either condition matches |
| `NOT` | Negate a condition |
| `EMPTY` | Alias for null/no value |
| `NULL` | Alias for empty/no value |
| `ORDER BY` | Sort results (`ASC` or `DESC`) |

## Quoting Rules

**Must quote values containing:**
- Spaces: `project = "My Project"`
- Special characters: `summary ~ "error@host"`
- Reserved words used as values: `labels = "AND"`

**No quotes needed for:**
- Single words: `status = Open`
- Project keys: `project = PROJ`
- Function calls: `assignee = currentUser()`

## Cloud vs Server/DC Differences

- **User references**: Cloud uses `accountId` (e.g. `assignee = "5b10ac8d82e05b22cc7d4ef5"`), Server/DC uses `username` (e.g. `assignee = "john.doe"`). The `currentUser()` function works on both.
- Functions like `currentUser()`, `membersOf()`, date functions, and sprint functions work on both platforms.

## Sources

**Cloud:**
- [JQL Operators](https://support.atlassian.com/jira-software-cloud/docs/jql-operators/)
- [JQL Functions](https://support.atlassian.com/jira-software-cloud/docs/jql-functions/)
- [JQL Keywords](https://support.atlassian.com/jira-software-cloud/docs/jql-keywords/)

**Server/Data Center:**
- [JQL Operators (Server/DC)](https://confluence.atlassian.com/jirasoftwareserver/advanced-searching-operators-reference-939938753.html)
- [JQL Functions (Server/DC)](https://confluence.atlassian.com/jirasoftwareserver/advanced-searching-functions-reference-939938746.html)
- [JQL Keywords (Server/DC)](https://confluence.atlassian.com/jirasoftwareserver/advanced-searching-keywords-reference-939938757.html)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall