# Jira Reader

> Read-only Jira navigation and analytics via the jira-sandbox MCP server (mcp__jira-sandbox__* tools). Use whenever the user asks about Jira in any form — a ticket key like PROJ-123, sprint or backlog status, standup prep, what's blocked, or metrics like velocity, cycle time, and project health. NEVER calls Jira write tools — when the user asks to change Jira (create, comment, transition, sprint moves), use jira-writer instead.

- Skill: `artsmc-claude-dev-agents/jira-reader` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add artsmc-claude-dev-agents/jira-reader`
- Raw SKILL.md: https://api.skillmd.com/api/skills/artsmc-claude-dev-agents/jira-reader/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: artsmc (https://skillmd.com/u/artsmc-claude-dev-agents)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/artsmc-claude-dev-agents/jira-reader

---


# Jira Reader

Navigate and analyze Jira **read-only** through the `jira-sandbox` MCP server.

## Read-only contract (the point of this skill)

The MCP server also exposes write tools, but this skill never touches them.
**Never call these seven tools from jira-reader**, even if the user asks directly:

`create_jira_issue`, `update_jira_issue`, `add_jira_comment`, `transition_jira_issue`,
`link_issues_to_epic`, `add_issues_to_sprint`, `set_story_points`

When the user asks for a change ("comment on X", "move Y to Done", "create a ticket"),
that's the **jira-writer** skill's job — it does writes with read-first, preview, and
explicit confirmation. Switch to it. If jira-writer isn't available in the session,
do the read half here (pull up the issue for context), give the user a paste-ready
draft of the change, and say writes need the jira-writer skill.

All other tools on this server are reads and are fair game.

## Connectivity & setup

- The server lives behind an internal VPN-only ALB. If calls fail with connection
  errors or timeouts, the VPN is off — tell the user to connect, don't debug the
  server. A read that worked minutes ago and now times out almost always means VPN drop.
- Tool names are `mcp__jira-sandbox__<tool>`. If they aren't loaded in this session yet,
  load them with ToolSearch (e.g. query `+jira search issue` or
  `select:mcp__jira-sandbox__search_jira_issues`).
- Auth is server-side (shared service account), so JQL `currentUser()` refers to the
  service account, **not** the user. To scope to a person, ask for or infer their Jira
  display name and use `assignee = "First Last"`.

## Core navigation tools

| Tool | Use for | Key params |
|------|---------|-----------|
| `list_jira_projects` | Discover project keys. Run this whenever the user names a project ambiguously instead of guessing a key. | — |
| `search_jira_issues` | Any issue lookup beyond a single known key. | `jql` (required), `max_results` (default small — 10–20) |
| `get_jira_issue` | Full detail on one issue. | `issue_key` |
| `get_issue_changelog` | Status history of one issue — "when did this move to In Progress?" | `issue_key` |
| `get_jira_transitions` | What statuses an issue *could* move to (read-only metadata — fine to call). | `issue_key` |
| `get_sprints` | List a board's sprints. | `project_key`, `state` (`active`/`future`/`closed`) |
| `get_sprint_issues` | Issues + status breakdown in one sprint. | `sprint_id` (from `get_sprints`), `project_key` |

Results come back as formatted text (not JSON): issue key, summary, status, assignee.
Summarize and reshape it for the user — lead with the answer, don't dump raw tool output.

## JQL & playbooks

Before composing any JQL or running a multi-step read (ticket lookup, project
catch-up, sprint status, standup prep, health check), read
`references/jql-cookbook.md` — JQL query recipes plus step-by-step playbooks.

## Analytics tools (all read-only, mostly just need `project_key`)

Pick the narrowest tool that answers the question instead of running many:

- **Flow / speed**: `get_cycle_time`, `get_lead_time`, `get_throughput`, `get_flow_efficiency`, `get_issue_aging`, `get_wip_count`, `get_context_switching`
- **Sprint**: `get_sprint_velocity`, `get_sprint_burndown`, `get_sprint_scope_change`, `get_commitment_reliability`, `get_sprint_predictability`, `predict_sprint_completion` (Monte Carlo forecast)
- **Quality / bugs**: `get_bug_metrics`, `get_reopen_rate`, `get_first_time_resolution_rate`, `get_defect_escape_rate`, `get_mttr`, `get_technical_debt_time`
- **Planning / backlog**: `get_backlog_health`, `get_created_vs_resolved`, `get_epic_progress`, `get_release_burndown`, `get_deadline_adherence`, `get_estimation_accuracy`, `get_interrupt_tracking`
- **People / load** (be tactful — these compare individuals): `get_developer_velocity`, `get_assignment_balance`, `get_handoff_frequency`, `get_capacity_allocation`
- **Risk / attention**: `get_blocked_issues`, `get_security_ticket_aging`, `get_project_health` (composite score — good single call for "how is project X doing?")

Time-windowed tools take `time_range_days`; sprint-windowed ones take `num_sprints`.

## Reporting style

Answer the question first, in prose. Use a short table only when listing several issues
(key, summary, status, assignee). Always show issue keys so the user can jump to Jira.
For metrics, give the headline number plus what it means ("P50 cycle time 4.2 days —
typical story takes about a week"), not a stats dump. Flag empty/sparse data honestly —
sandbox projects may have little history, which makes percentile metrics unreliable.