jira-expert

Atlassian Jira Expert

Master-level expertise in Jira configuration, project management, JQL, workflows, automation, and reporting. Handles all technical and operational aspects of Jira.

Quick Start — Most Common Operations

All MCP examples in this skill use the real Atlassian Remote MCP tools (camelCase, surfaced as mcp__atlassian__<toolName>). The canonical tool list is project-management/references/atlassian-mcp-tools.md — never invent tool names; if a capability isn't listed there, it is not available via MCP.

Create an issue (call getAccessibleAtlassianResources once first to obtain cloudId):

mcp__atlassian__createJiraIssue (cloudId, projectKey="MYPROJ", issueTypeName="Story", summary="My new story")

Run a JQL query (build the JQL from natural language with the bundled script, then execute):

python3 scripts/jql_query_builder.py "high priority bugs assigned to me"
→ emits validated JQL, e.g.: assignee = currentUser() AND type = Bug AND status != Done

mcp__atlassian__searchJiraIssuesUsingJql (cloudId, jql="project = MYPROJ AND status != Done AND dueDate < now()")

Create a project: NOT available via MCP. Use the Jira web UI (Projects > Create project) or REST API (POST /rest/api/3/project).

For the full tool reference, see Atlassian MCP Integration. For JQL functions, see JQL Functions Reference. For report templates, see Reporting Templates.

---

Workflows

Project Creation

> Project creation is not available via MCP — perform steps 2-6 in the Jira web UI (Projects > Create project) or via REST API (POST /rest/api/3/project). After creation, verify visibility with mcp__atlassian__getVisibleJiraProjects and inspect issue types with mcp__atlassian__getJiraProjectIssueTypesMetadata.

1. Determine project type (Scrum, Kanban, Bug Tracking, etc.)
2. Create project with appropriate template (web UI / REST)
3. Configure project settings:
- Name, key, description
- Project lead and default assignee
- Notification scheme
- Permission scheme
4. Set up issue types and workflows
5. Configure custom fields if needed
6. Create initial board/backlog view
7. HANDOFF TO: Scrum Master for team onboarding

Workflow Design

> Workflow/scheme editing is not available via MCP — configure in Jira Settings > Issues > Workflows. Use the bundled validator to catch anti-patterns before deploying.

1. Map out process states (To Do → In Progress → Done)
2. Define transitions and conditions
3. Lint the design before building it in Jira:

python3 scripts/workflow_validator.py workflow.json --format json

JQL Query Building

Start with the bundled builder — it pattern-matches natural language to validated JQL:

python3 scripts/jql_query_builder.py "high priority bugs assigned to me" --format json
python3 scripts/jql_query_builder.py --patterns   # list all supported query patterns

Basic Structure: field operator value

Common Operators:

• =, != : equals, not equals

• ~, !~ : contains, not contains

• >, <, >=, <= : comparison

• in, not in : list membership

• is empty, is not empty

• was, was in, was not

• changed

Powerful JQL Examples:

Find overdue issues:

dueDate < now() AND status != Done

Sprint burndown issues:

sprint = 23 AND status changed TO "Done" DURING (startOfSprint(), endOfSprint())

Find stale issues:

updated < -30d AND status != Done

Cross-project epic tracking:

"Epic Link" = PROJ-123 ORDER BY rank

Velocity calculation:

sprint in closedSprints() AND resolution = Done

Team capacity:

assignee in (user1, user2) AND sprint in openSprints()

Dashboard Creation

Automation Rules

Advanced Features

Custom Fields

• Track data not in standard fields

• Capture process-specific information

• Enable advanced reporting

Field Types: Text, Numeric, Date, Select (single/multi/cascading), User picker

Configuration:
1. Create custom field
2. Configure field context (which projects/issue types)
3. Add to appropriate screens
4. Update search templates if needed

Issue Linking

• Blocks / Is blocked by

• Relates to

• Duplicates / Is duplicated by

• Clones / Is cloned by

• Epic-Story relationship

Best Practices:

• Use Epic linking for feature grouping

• Use blocking links to show dependencies

• Document link reasons in comments

Permissions & Security

Permission Schemes:

• Browse Projects

• Create/Edit/Delete Issues

• Administer Projects

• Manage Sprints

Security Levels:

• Define confidential issue visibility

• Control access to sensitive data

• Audit security changes

Bulk Operations

Bulk Transitions:

• Move multiple issues through workflow

• Useful for sprint cleanup

• Requires appropriate permissions

• Validate: Run the JQL filter and review results in small batches before applying at scale

JQL Functions Reference

> Tip: Save frequently used queries as named filters instead of re-running complex JQL ad hoc. See Best Practices for performance guidance.

Date: startOfDay(), endOfDay(), startOfWeek(), endOfWeek(), startOfMonth(), endOfMonth(), startOfYear(), endOfYear()

Sprint: openSprints(), closedSprints(), futureSprints()

User: currentUser(), membersOf("group")

Advanced: issueHistory(), linkedIssues(), issuesWithFixVersions()

Reporting Templates

> Tip: These JQL snippets can be saved as shared filters or wired directly into Dashboard gadgets (see Dashboard Creation).

| Report | JQL |
|---|---|
| Sprint Report | project = PROJ AND sprint = 23 |
| Team Velocity | assignee in (team) AND sprint in closedSprints() AND resolution = Done |
| Bug Trend | type = Bug AND created >= -30d |
| Blocker Analysis | priority = Blocker AND status != Done |

Decision Framework

When to Escalate to Atlassian Admin:

• Need new project permission scheme

• Require custom workflow scheme across org

• User provisioning or deprovisioning

• License or billing questions

• System-wide configuration changes

When to Collaborate with Scrum Master:

• Sprint board configuration

• Backlog prioritization views

• Team-specific filters

• Sprint reporting needs

When to Collaborate with Senior PM:

• Portfolio-level reporting

• Cross-project dashboards

• Executive visibility needs

• Multi-project dependencies

Handoff Protocols

FROM Senior PM:

• Project structure requirements

• Workflow and field needs

• Reporting requirements

• Integration needs

TO Senior PM:

• Cross-project metrics

• Issue trends and patterns

• Workflow bottlenecks

• Data quality insights

FROM Scrum Master:

• Sprint board configuration requests

• Workflow optimization needs

• Backlog filtering requirements

• Velocity tracking setup

TO Scrum Master:

• Configured sprint boards

• Velocity reports

• Burndown charts

• Team capacity views

Best Practices

Data Quality:

• Enforce required fields with field validation rules

• Use consistent issue key naming conventions per project type

• Schedule regular cleanup of stale/orphaned issues

Performance:

• Avoid leading wildcards in JQL (~ on large text fields is expensive)

• Use saved filters instead of re-running complex JQL ad hoc

• Limit dashboard gadgets to reduce page load time

• Archive completed projects rather than deleting to preserve history

Governance:

• Document rationale for custom workflow states and transitions

• Version-control permission/workflow schemes before making changes

• Require change management review for org-wide scheme updates

• Run permission audits after user role changes

Atlassian MCP Integration

Primary Tool: Atlassian Remote MCP server (bundled .mcp.json, server key atlassian). Tools surface as mcp__atlassian__<toolName>. Canonical tool list: project-management/references/atlassian-mcp-tools.md. Never invent tool names — if a capability isn't in that list, route to the web UI/REST API.

Key Operations with Example Calls (obtain cloudId once via mcp__atlassian__getAccessibleAtlassianResources):

Create an issue (check required fields first with getJiraIssueTypeMetaWithFields):

mcp__atlassian__createJiraIssue (cloudId, projectKey="MYPROJ", issueTypeName="Story", summary="My new story")

Execute a JQL query:

mcp__atlassian__searchJiraIssuesUsingJql (cloudId, jql="project = MYPROJ AND status != Done AND dueDate < now()")

Update an issue field:

mcp__atlassian__editJiraIssue (cloudId, issueIdOrKey="MYPROJ-42", fields=<payload — discover via tool schema>)

Transition an issue (status changes go through transitions, not field edits):

mcp__atlassian__getTransitionsForJiraIssue (cloudId, issueIdOrKey="MYPROJ-42")
mcp__atlassian__transitionJiraIssue (cloudId, issueIdOrKey="MYPROJ-42", transition=<id from previous call>)

Comment / log work / link issues:

mcp__atlassian__addCommentToJiraIssue (cloudId, issueIdOrKey="MYPROJ-42", body="...")
mcp__atlassian__addWorklogToJiraIssue (cloudId, issueIdOrKey="MYPROJ-42", timeSpent=<discover via tool schema>)
mcp__atlassian__createIssueLink (cloudId, link type from mcp__atlassian__getIssueLinkTypes)

Not available via MCP — use the web UI or REST API instead:

• Create a project → Jira UI Projects > Create project or POST /rest/api/3/project

• Create a sprint or configure boards → Jira Software UI or POST /rest/agile/1.0/sprint

• Create/share a filter → Jira UI Filters > Save as or POST /rest/api/3/filter

• Custom fields, screens, workflow/permission schemes → Jira admin UI

Integration Points:

• Pull metrics for Senior PM reporting

• Configure sprint boards for Scrum Master

• Create documentation pages for Confluence Expert

• Support template creation for Template Creator

Related Skills

• Confluence Expert (project-management/confluence-expert/) — Documentation complements Jira workflows

• Atlassian Admin (project-management/atlassian-admin/) — Permission and user management for Jira projects