Jira

Jira

Purpose

This skill provides comprehensive Jira project management capabilities through the Atlassian MCP integration. It enables agents to create, update, search, comment on, and link issues programmatically. Use this skill whenever a task involves managing work items in Jira — whether creating new tickets, updating existing ones, querying backlogs, or orchestrating cross-issue relationships.

Issue Types & Hierarchy

Hierarchy (top → bottom)

Epic
 └── Story / Task / Bug
      └── Sub-task

Issue Types

Hierarchy Rules

• Epics contain Stories, Tasks, and Bugs (via Epic Link field).
• Stories, Tasks, and Bugs can have Sub-tasks.
• Sub-tasks cannot have children.
• Every Story/Task/Bug should belong to an Epic unless it is truly standalone.

Fields Reference

Required Fields

Common Optional Fields

Summary Writing Conventions

• Imperative mood: "Add user authentication" not "Added user authentication" or "Adding user authentication"
• Under 80 characters: Be concise but specific
• No trailing period: Summaries are titles, not sentences
• Include scope hint: "[API] Add rate limiting to /users endpoint"
• Bug summaries state the symptom: "Login fails with 500 when email contains +"

Description Templates

Story Description:

h2. User Story
As a [persona], I want [action] so that [benefit].

h2. Acceptance Criteria
* [ ] Criterion 1
* [ ] Criterion 2
* [ ] Criterion 3

h2. Technical Notes
* Implementation approach or constraints
* Relevant endpoints, schemas, dependencies

h2. Out of Scope
* What this story explicitly does NOT cover

Bug Description:

h2. Summary
Brief description of the defect.

h2. Steps to Reproduce
# Step 1
# Step 2
# Step 3

h2. Expected Behavior
What should happen.

h2. Actual Behavior
What actually happens. Include error messages, status codes, screenshots.

h2. Environment
* Browser/OS/Device:
* Version/Build:
* Environment: staging / production

h2. Severity Assessment
* Impact: [Critical / High / Medium / Low]
* Frequency: [Always / Often / Sometimes / Rarely]
* Workaround: [None / Exists — describe]

Workflow States

Standard Workflow

To Do → In Progress → In Review → Done

Transition Rules

• Only transition forward unless explicitly reverting (e.g., review rejection → In Progress).
• Moving to "In Progress" should set/confirm the assignee.
• Moving to "Done" should verify all sub-tasks are also Done.

Issue Link Types

MCP Tools Available

jira_create_issue

Create a new Jira issue.

Parameters: project, summary, issuetype, description?, priority?, labels?, components?, assignee?, parent? (for sub-tasks)
Returns: key, id, self (URL)

jira_update_issue

Update fields on an existing issue.

Parameters: issue_key, fields (object with fields to update)
Returns: confirmation

jira_add_comment

Add a comment to an existing issue.

Parameters: issue_key, body (comment text)
Returns: comment ID, created timestamp

jira_link_issues

Create a link between two issues.

Parameters: inward_issue, outward_issue, link_type
Returns: confirmation

jira_search

Search issues using JQL.

Parameters: jql, fields? (array of field names), max_results?
Returns: array of matching issues

jira_get_issue

Retrieve full details of a single issue.

Parameters: issue_key
Returns: full issue object with all fields

jira_transition_issue

Move an issue to a new workflow state.

Parameters: issue_key, transition_id or transition_name
Returns: confirmation

JQL Quick Reference

Common Queries

-- My open issues
assignee = currentUser() AND status != Done

-- Sprint backlog
sprint in openSprints() AND project = PROJ

-- Unresolved bugs by priority
project = PROJ AND issuetype = Bug AND status != Done ORDER BY priority ASC

-- Recently updated
project = PROJ AND updated >= -7d ORDER BY updated DESC

-- Blocked work
issuefunction in hasLinks("is blocked by")

-- Epics missing stories
issuetype = Epic AND project = PROJ AND NOT issuefunction in hasLinks("is Epic of")

-- Issues without estimates
project = PROJ AND issuetype in (Story, Task) AND story_points is EMPTY AND sprint in openSprints()

JQL Operators

JQL Functions

Comment Conventions

• Status updates: Start with the new state. "In Progress — starting backend implementation."
• Questions: Tag the person. "@john.doe — can you clarify the auth flow for SSO users?"
• Blockers: Flag clearly. "BLOCKED — waiting on PROJ-456 (API schema finalization)."
• Completion: Summarize what was done. "Done — implemented rate limiter with token bucket algorithm. See PR #234."
• Technical notes: Use code blocks for snippets, stack traces, or config.

Conventions

1. Always search before creating — avoid duplicates. Run a JQL query for similar summaries first.
2. One ticket, one concern — don't bundle unrelated work into a single issue.
3. Link related issues — if two tickets touch the same code or feature, link them.
4. Keep summaries scannable — a PM should understand the ticket from the summary alone.
5. Set priority explicitly — never leave priority as the default unless it truly is Medium.
6. Assign during sprint planning — not at creation time, unless the assignee is obvious.
7. Sub-tasks for decomposition — if a Story has >3 days of work, break it into Sub-tasks.

Knowledge Strategy

• Patterns to capture: Project-specific field mappings (custom field IDs), common JQL queries that prove useful, description templates refined for specific teams.
• Examples to collect: Successfully created ticket payloads, effective bug reports, JQL queries for recurring audits.
• Update permission: Agents may freely add/update files in references/. Changes to SKILL.md or scripts/ require user approval.