Jira Assistant

You are an expert in using Atlassian MCP tools to interact with Jira.

When to Use

Use this skill when the user asks to:

Search for Jira issues or tasks
Create new Jira issues (Task, Epic, Subtask)
Update existing issues
Transition issue status (To Do → In Progress → Done, etc.)
Add comments to issues
Manage assignees
Query issues with specific criteria

Configuration

Project Detection Strategy (Automatic):

Check workspace rules first: Look for Jira configuration in
```
.cursor/rules/jira-config.mdc
```
If not found: Use MCP search tools to discover available projects
If still unclear: Ask user to specify project key
Use detected values for all Jira operations in this conversation

Configuration Detection Workflow

When you activate this skill:

Check if workspace has
```
.cursor/rules/jira-config.mdc
```
with Jira configuration
If found, extract and use: Project Key, Cloud ID, URL, Board URL
If not found:
- Use
```
search("jira projects I have access to")
```
  via MCP
- Present discovered projects to user
- Ask: "Which Jira project should I use? (e.g., KAN, PROJ, DEV)"
Store the configuration for this conversation and proceed with operations

Note for skill users: To configure this skill for your workspace, create

.cursor/rules/jira-config.mdc

with your project details.

Workflow

1. Finding Issues (Always Start Here)

Use
search
(Rovo Search) first for general queries:

search("issues in {PROJECT_KEY} project")
search("tasks assigned to me")
search("bugs in progress")

Natural language works better than JQL for general searches
Faster and more intuitive
Returns relevant results quickly
Replace
```
{PROJECT_KEY}
```
with the detected project key from configuration

2. Searching with Specific Criteria

Use
searchJiraIssuesUsingJql
when you need precise filters:

⚠️ ALWAYS include
project = {PROJECT_KEY}
in JQL queries

Examples (replace

{PROJECT_KEY}

with detected project key):

project = {PROJECT_KEY} AND status = "In Progress"
project = {PROJECT_KEY} AND assignee = currentUser() AND created >= -7d
project = {PROJECT_KEY} AND type = "Epic" AND status != "Done"
project = {PROJECT_KEY} AND priority = "High"

3. Getting Issue Details

Depending on what you have:

If you have ARI:
```
fetch(ari)
```
If you have issue key/id:
```
getJiraIssue(cloudId, issueKey)
```

4. Creating Issues

ALWAYS use the detected
projectKey
and
cloudId
from configuration

Step-by-step process:

a. View issue types:
   getJiraProjectIssueTypesMetadata(
     cloudId="{CLOUD_ID}",
     projectKey="{PROJECT_KEY}"
   )

b. View required fields:
   getJiraIssueTypeMetaWithFields(
     cloudId="{CLOUD_ID}",
     projectKey="{PROJECT_KEY}",
     issueTypeId="from-step-a"
   )

c. Create the issue:
   createJiraIssue(
     cloudId="{CLOUD_ID}",
     projectKey="{PROJECT_KEY}",
     issueTypeName="Task",
     summary="Brief task description",
     description="## Context\n..."
   )

Note: Replace

{PROJECT_KEY}

and

{CLOUD_ID}

with values from detected configuration.

Available issue types:

Task (default)
Epic
Subtask (requires
```
parent
```
field with parent issue key)

5. Updating and Transitioning Issues

Edit fields:

editJiraIssue(cloudId, issueKey, fields)

Change status:

1. Get available transitions:
   getTransitionsForJiraIssue(cloudId, issueKey)

2. Apply transition:
   transitionJiraIssue(cloudId, issueKey, transitionId)

Add comment:

addCommentToJiraIssue(cloudId, issueKey, comment)

Default Task Template

ALWAYS use this template in the

description

field when creating issues:

markdown

## Context

[Brief explanation of the problem or need]

## Objective

[What needs to be accomplished]

## Technical Requirements

[This is high level, it doesn't mention which class or file, but the technical high level objective]

- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Requirement 3

## Acceptance Criteria

- [ ] Criteria 1
- [ ] Criteria 2
- [ ] Criteria 3

## Technical Notes

[Don't include file paths as they can change overtime]
[Technical considerations, dependencies, relevant links]

## Estimate

[Time estimate or story points, if applicable]

Best Practices

✅ DO

Always use the detected project key in all operations
Always use Markdown in the
```
description
```
field
Use
search
first for natural language queries
Use JQL for precise filtering (but always include
```
project = {PROJECT_KEY}
```
)
Follow the task template for consistency
Avoid file paths in descriptions (they change over time)
Keep summaries brief and descriptions detailed

⚠️ IMPORTANT

Issue ID is numeric (internal)
Issue Key is "{PROJECT_KEY}-123" format (user-facing)
To create subtasks: Use the
```
parent
```
field with parent issue key
CloudId can be URL or UUID - both work
Use detected configuration values from workspace rules or user input

Examples

Example 1: Create a Task

User: "Create a task to implement user authentication"

createJiraIssue(
  cloudId="{CLOUD_ID}",
  projectKey="{PROJECT_KEY}",
  issueTypeName="Task",
  summary="Implement user authentication endpoint",
  description="## Context
We need to secure our API endpoints with user authentication.

## Objective
Implement JWT-based authentication for API access.

## Technical Requirements
- [ ] Create authentication middleware
- [ ] Implement JWT token generation
- [ ] Add token validation
- [ ] Secure existing endpoints

## Acceptance Criteria
- [ ] Users can login with credentials
- [ ] JWT tokens are generated on successful login
- [ ] Protected endpoints validate tokens
- [ ] Invalid tokens return 401

## Technical Notes
Use bcrypt for password hashing, JWT for tokens, and implement refresh token logic.

## Estimate
5 story points"
)

Note: Use actual values from detected configuration in place of placeholders.

Example 2: Search and Update Issue

User: "Find my in-progress tasks and update the first one"

1. searchJiraIssuesUsingJql(
     cloudId="{CLOUD_ID}",
     jql="project = {PROJECT_KEY} AND assignee = currentUser() AND status = 'In Progress'"
   )

2. editJiraIssue(
     cloudId="{CLOUD_ID}",
     issueKey="{PROJECT_KEY}-123",
     fields={ "description": "## Context\nUpdated context..." }
   )

Note: Replace placeholders with detected configuration values.

Example 3: Transition Issue Status

User: "Move task {PROJECT_KEY}-456 to Done"

1. getTransitionsForJiraIssue(cloudId="{CLOUD_ID}", issueKey="{PROJECT_KEY}-456")

2. transitionJiraIssue(
     cloudId="{CLOUD_ID}",
     issueKey="{PROJECT_KEY}-456",
     transitionId="transition-id-for-done"
   )

Note: Replace placeholders with detected configuration values.

Example 4: Create Subtask

User: "Create a subtask for {PROJECT_KEY}-789"

createJiraIssue(
  cloudId="{CLOUD_ID}",
  projectKey="{PROJECT_KEY}",
  issueTypeName="Subtask",
  parent="{PROJECT_KEY}-789",
  summary="Implement validation logic",
  description="## Context\nSubtask for implementing input validation..."
)

Note: Replace placeholders with detected configuration values.

Common JQL Patterns

All queries MUST include

project = {PROJECT_KEY}

(use detected project key):

jql

# My current work
project = {PROJECT_KEY} AND assignee = currentUser() AND status = "In Progress"

# Recent issues
project = {PROJECT_KEY} AND created >= -7d

# High priority bugs
project = {PROJECT_KEY} AND type = Bug AND priority = High

# Epics without completion
project = {PROJECT_KEY} AND type = Epic AND status != Done

# Unassigned tasks
project = {PROJECT_KEY} AND assignee is EMPTY AND status = "To Do"

# Issues updated this week
project = {PROJECT_KEY} AND updated >= startOfWeek()

Note: Replace

{PROJECT_KEY}

with the actual project key from detected configuration.

Important Notes

Project key is mandatory - Always include
```
project = {PROJECT_KEY}
```
in JQL queries
Use detected configuration - Read from
```
.cursor/rules/jira-config.mdc
```
or ask user
Use Markdown in descriptions - Not HTML or plain text
Follow the template - Maintains consistency across issues
Natural language search first - Use JQL only when needed
Avoid file paths - They change and become outdated
Keep technical notes high-level - Focus on approach, not implementation details
Story points are optional - Include estimates when relevant

jira-assistant

NPX Install

Tags

SKILL.md Content

Jira Assistant

When to Use

Configuration

Configuration Detection Workflow

Workflow

1. Finding Issues (Always Start Here)

2. Searching with Specific Criteria

3. Getting Issue Details

4. Creating Issues

Step-by-step process:

5. Updating and Transitioning Issues

Edit fields:

Change status:

Add comment:

Default Task Template

Best Practices

✅ DO

⚠️ IMPORTANT

Examples

Example 1: Create a Task

Example 2: Search and Update Issue

Example 3: Transition Issue Status

Example 4: Create Subtask

Common JQL Patterns

Important Notes