Unified Jira interface — find users, get/create/search tickets, triage by project, track mentions, manage ticket cache with SWR invalidation. Use for any Jira operation, triage, or when other skills need Jira context.
Unified Jira interface: ticket operations, user lookups, triage, mentions tracking, and SWR-cached data access.
| Input | Mode | Agent-friendly |
|---|---|---|
find-user <name> | Find User — resolve name to Jira account ID | Yes |
get-ticket <KEY> | Get Ticket — fetch ticket with SWR cache | Yes |
create-ticket <project> <type> <summary> | Create Ticket — create a new issue | Yes |
search <JQL or keywords> | Search — JQL search or keyword search | Yes |
edit-ticket <KEY> <field> <value> | Edit — update a ticket field | Yes |
transition <KEY> <status> | Transition — move ticket to new status | Yes |
comment <KEY> <text> | Comment — add comment to ticket | Yes |
| Input | Mode | Agent-friendly |
|---|---|---|
mentions | Mentions — find @mentions of owner across tickets | |
triage [project] | Triage — scan project for unassigned/stale tickets | |
help [mode] | Help — list all modes with descriptions | Yes |
--json --quietSame behavior as x-slack: machine-readable JSON envelope, no prose. Agents should ALWAYS use this.
--freshBypass the SWR cache and force a fresh API call. Use when accuracy matters (e.g., right before transitioning a ticket or after making changes).
Shared (~/.claude/companies/{company}/data/):
| File | Purpose |
|---|---|
people.yml | Unified identity — Jira account IDs, Slack IDs, topics |
faq.yml | Shared knowledge base |
categories.yml | Shared category definitions |
Jira-specific (~/.claude/companies/{company}/data/jira/):
| File | Purpose |
|---|---|
ticket-tracker.yml | Active tickets being monitored (status, owner, priority) |
ticket-archive.yml | Resolved tickets archive (append-only, by month) |
classification-rules.yml | Jira-specific triage rules (project/component → category) |
cache.json | SWR ticket cache (JSON for performance, not human-edited) |
Policy file (~/.claude/policies/companies/{company}/jira-fields.yml):
The cache stores ticket data with TTLs. Stale data is returned immediately while a background refresh updates the cache.
TTLs by data type:
| Data type | TTL | Reasoning |
|---|---|---|
| Ticket metadata (summary, type, components) | 30 min | Rarely changes after creation |
| Ticket status/assignee | 10 min | Changes during active triage |
| Comments | 15 min | Arrive in bursts during investigation |
| User/identity data | 24 hr | Almost never changes |
| Field schemas (custom field IDs) | 7 days | Only changes when admin reconfigures |
Cache behavior:
cache.json--fresh flag → skip cache entirely, fetch from API, update cacheComment staleness check:
comment_count alongside comment datamcp__atlassian-redacted__get_jira_issue with minimal fields to get comment countEviction:
{
"meta": { "last_eviction": "2026-01-01T00:00:00", "entry_count": 0 },
"tickets": {
"PROJ-123": {
"fetched_at": "2026-01-01T00:00:00",
"last_accessed": "2026-01-01T00:00:00",
"data": {
"key": "PROJ-123",
"summary": "...",
"status": "In Progress",
"assignee_id": "...",
"priority": "High",
"components": [],
"labels": [],
"created": "2026-01-01",
"updated": "2026-01-01"
},
"comments": {
"fetched_at": "2026-01-01T00:00:00",
"count": 0,
"items": []
}
}
},
"users": {
"Alice Smith": {
"fetched_at": "2026-01-01T00:00:00",
"account_id": "712020:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
},
"field_schemas": {
"fetched_at": null,
"story_points": "customfield_10024"
}
}
Follow the PII protection policy (see ~/.claude/policies/pii-protection.md):
| Operation | MCP Tool |
|---|---|
| Read tickets (default) | mcp__atlassian-redacted__get_jira_issue |
| Lightweight status check | mcp__atlassian-redacted__get_ticket_summary — key, status, assignee, comment count, updated date. Use for SWR staleness checks and dashboards. |
| Comment count check | mcp__atlassian-redacted__check_comments_updated — pass known_count from cache, returns Changed true/false. If unchanged, extend TTL. If changed, do full refresh. |
| Health check | mcp__atlassian-redacted__health_check — call once on first Jira operation per session, and again on any unexpected error. Do NOT call before every operation. |
| Create/edit tickets | mcp__atlassian-redacted__create_jira_issue / edit_jira_issue (preferred), atlassian (fallback) |
| Add comments | mcp__atlassian-redacted__add_jira_comment (preferred), atlassian (fallback) |
| Search (JQL) | mcp__atlassian-redacted__search_jira_issues |
| User lookup | mcp__atlassian-redacted__lookup_jira_account_id first, atlassian if no results (with user warning) |
| Transitions | mcp__atlassian-redacted__get_jira_transitions + transition_jira_issue |
| Confluence | atlassian only (warn user first) |
Resolve a name to Jira account ID. Checks people.yml cache first.
Input: find-user <name> — partial match, case-insensitive
people.yml for matching name/alias → return cached jira_id if foundjira_id is null: call mcp__atlassian-redacted__lookup_jira_account_idmcp__atlassian__lookupJiraAccountId (with PII warning)people.yml with the discovered jira_idcache.json under usersFetch a ticket with SWR cache.
Input: get-ticket <KEY> (e.g., get-ticket PROJ-123)
^[a-zA-Z]{2,12}-\d{1,7}$, normalize to uppercase--fresh: skip cache, fetch via mcp__atlassian-redacted__get_jira_issue, update cachecache.json → if within TTL, serve from cachemcp__atlassian-redacted__get_ticket_summary for lightweight staleness check
mcp__atlassian-redacted__get_jira_issuemcp__atlassian-redacted__check_comments_updated with cached comment count
Create a new Jira issue.
Input: create-ticket <project> <type> <summary> — or --json with full field body
mcp__atlassian-redacted__create_jira_issueticket-tracker.yml if it matches monitored criteriaSearch Jira via JQL or keywords.
Input: search <query>
=, IN, ORDER BY, etc.) → pass as raw JQLtext ~ "query" ORDER BY updated DESCmcp__atlassian-redacted__search_jira_issuescache.jsonUpdate a field on a ticket.
Input: edit-ticket <KEY> <field> <value>
mcp__atlassian-redacted__edit_jira_issueMove a ticket to a new status.
Input: transition <KEY> <status>
mcp__atlassian-redacted__get_jira_transitions to get available transitions<status> to transition name (fuzzy, case-insensitive)mcp__atlassian-redacted__transition_jira_issueAdd a comment to a ticket.
Input: comment <KEY> <text>
mcp__atlassian-redacted__add_jira_commentFull @mentions scan with WSJF prioritization, smart batching, delta tracking, and snapshot management.
Input: mentions [days] — lookback days, default 14
Full workflow: See mentions-workflow.md for the complete 10-step workflow including:
(Priority + Staleness + Sprint) / Story Pointsdata/mentions/Quick summary (what this mode does at a high level):
people.ymlScan a Jira project for items needing attention.
Input: triage [project] — default: scan all configured projects
classification-rules.yml for Jira-specific classification rulescategories.yml for category definitionspeople.yml for routingclassification-rules.ymlpeople.yml topicsticket-tracker.yml with findingsSame pattern as x-slack help. Lists all modes with descriptions, args, examples.
Input: help [mode]
Same envelope as x-slack:
{
"mode": "get-ticket|search|find-user|...",
"ok": true,
"count": 1,
"results": [ ... ],
"errors": [],
"cache_hit": true,
"cache_age_seconds": 245
}
Extra fields for cache-aware modes: cache_hit (bool), cache_age_seconds (int, null if miss).
Spawn: Agent tool, subagent_type: general-purpose
Task: Search Jira for [query]. For each result, get ticket details.
Return: list of {key, summary, status, assignee, priority, updated}
Same pattern as x-slack agent — see agent-prompt.md
Other skills call x-jira modes directly with --json --quiet:
1. /x-jira get-ticket PROJ-123 --json --quiet
→ Cached ticket data (or fresh if stale)
2. /x-jira search "auth failure" --json --quiet
→ Related tickets
3. /x-jira find-user Alice --json --quiet
→ Jira account ID from people.yml cache
4. After fixing: /x-jira transition PROJ-123 "In Review" --json --quiet
5. /x-jira comment PROJ-123 "Fixed in PR #42" --json --quiet
1. /x-jira get-ticket PROJ-123 --fresh --json --quiet
→ Fresh data before final status check
2. /x-jira transition PROJ-123 "Done" --json --quiet
Other agents call /x-jira help --json --quiet to discover modes at runtime.