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
   Input: a JSON file with the workflow's states and transitions. Consume the output: fix every reported anti-pattern (dead-end states, unreachable states, missing transitions) in the design before touching Jira.
4. Add validators, post-functions, and conditions; configure the workflow scheme (web UI)
5. Validate: Deploy to a test project first; verify all transitions, conditions, and post-functions behave as expected before associating with production projects
6. Associate workflow with project
7. Test workflow with sample issues — via MCP: mcp__atlassian__getTransitionsForJiraIssue on a sample issue to confirm expected transitions surface, then mcp__atlassian__transitionJiraIssue to walk it through the flow

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

Consume the output: take the jql field from the JSON result (or the GENERATED JQL block in text mode) and execute it with mcp__atlassian__searchJiraIssuesUsingJql (cloudId, jql=<generated>). If the builder reports no pattern match, compose JQL manually using the reference below.

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

1. Create new dashboard (personal or shared)
2. Add relevant gadgets:
   • Filter Results (JQL-based)
   • Sprint Burndown
   • Velocity Chart
   • Created vs Resolved
   • Pie Chart (status distribution)
3. Arrange layout for readability
4. Configure automatic refresh
5. Share with appropriate teams
6. HANDOFF TO: Senior PM or Scrum Master for use

Automation Rules

1. Define trigger (issue created, field changed, scheduled)
2. Add conditions (if applicable)
3. Define actions:
   • Update field
   • Send notification
   • Create subtask
   • Transition issue
   • Post comment
4. Test automation with sample data
5. Enable and monitor

Advanced Features

Custom Fields

When to Create:

• 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

Link Types:

• 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 Change:

1. Use JQL to find target issues
2. Select bulk change operation
3. Choose fields to update
4. Validate: Preview all changes before executing; confirm the JQL filter matches only intended issues — bulk edits are difficult to reverse
5. Execute and confirm
6. Monitor background task

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).

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