mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-15 21:46:29 +03:00
0dd8d47cab
* fix(jira): gate mutating CLI operations Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> * fix(jira): defer client annotation resolution Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --------- Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
55 lines
3.2 KiB
Markdown
55 lines
3.2 KiB
Markdown
# Jira Issue Tracker from the Terminal
|
|
|
|
Interact with Atlassian Jira Cloud via the REST API v3: search issues with JQL, view details, create issues, add comments, count matches, list projects, and transition status — plus a full JQL language reference built in.
|
|
|
|
## Why Install This Skill
|
|
|
|
When your agent loads this skill, it can **run your entire Jira workflow** without opening a browser:
|
|
|
|
- **Search anything** — by project, assignee, or arbitrary JQL; results over 50 auto-paginate
|
|
- **Count before diving in** — fast approximate counts instead of fetching every ticket
|
|
- **Create, comment, edit** — with Atlassian Document Format handled for you
|
|
- **Transition safely** — discovers valid workflow transitions per issue before changing status, and can set resolutions in the same call
|
|
- **Write better queries** — a 50-query cookbook by role, complete function catalog, performance rules, and history-operator/date-expression deep dives
|
|
|
|
The skill also knows where the bodies are buried: the legacy-vs-enhanced search endpoint split (offset paging vs `nextPageToken`), transition screens that silently require resolution fields, the `!=` empty-value trap, and rate-limit headers worth honoring.
|
|
|
|
## What You Get
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `SKILL.md` | Command reference: setup, intent-grouped commands, pipeline recipes, jq guidance, known gotchas |
|
|
| `scripts/jira` | CLI tool for Jira REST API v3 (`--json`, `--dry-run`, lazy auth) |
|
|
| `scripts/test_jira.py` | Offline test suite for the CLI (help/errors/dry-run/mocked client logic) |
|
|
| `references/rest-auth-and-search.md` | Auth models, rate limits, error envelopes, search pagination duality |
|
|
| `references/rest-issues-and-transitions.md` | Issue CRUD shapes, transitions GET→POST flow, ADF document model |
|
|
| `references/jql-functions-catalog.md` | Every JQL function with fields and operators, incl. JSM approvals & SLAs |
|
|
| `references/jql-best-practices.md` | Performance rules, precedence, empty-value trap, troubleshooting flows |
|
|
| `references/jql-cookbook.md` | 50 ready-to-run JQL queries organized by role |
|
|
| `references/jql-history-and-dates.md` | WAS/CHANGED walkthrough, relative-date tables, saved-filter naming |
|
|
| `evals/evals.json` | Behavioral eval cases covering read-only use, pipelines, gotchas |
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
export JIRA_EMAIL="you@company.com"
|
|
export JIRA_API_TOKEN="YOUR_API_TOKEN" # free from https://id.atlassian.com/manage/api-tokens
|
|
export JIRA_SERVER="https://your-domain.atlassian.net"
|
|
|
|
jira me # verify auth works
|
|
jira list --project PROJ # newest tickets
|
|
jira count --jql 'issuetype = Bug AND resolution = Unresolved'
|
|
jira create --project PROJ --summary "Test" --dry-run # preview writes
|
|
jira --yes create --project PROJ --summary "Test" # authorize a write
|
|
```
|
|
|
|
## Triggers
|
|
|
|
Load this when managing Jira issues, searching or counting tickets, creating bugs, transitioning sprint work, writing/debugging/optimizing JQL, or designing saved filters and dashboards on an Atlassian Jira Cloud site.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.8+ with the `requests` library
|
|
- A free Atlassian account + API token (`JIRA_EMAIL`, `JIRA_API_TOKEN`; optional `JIRA_SERVER`)
|
|
- `jq` recommended for processing `--json` output
|