jira-assistant

description	Expert in Jira operations using Atlassian MCP - automatically detects workspace Jira configuration or prompts for project details. Use for searching, creating, updating issues, managing status transitions, and handling tasks.
name	Jira Assistant

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

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

Configuration Detection Workflow

When you activate this skill:

1. Check if workspace has .cursor/rules/jira-config.mdc with Jira configuration
2. If found, extract and use: Project Key, Cloud ID, URL, Board URL
3. 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)"
4. 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:

## 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):

# 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