jira-expert – skill Viết lách & Nội dung cho agent AI

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](#atlassian-mcp-integration). For JQL functions, see [JQL Functions Reference](#jql-functions-reference). For report templates, see [Reporting Templates](#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](#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](#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:

… (nội dung đầy đủ có trong gói tải về)