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 >= -7dproject = {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="## ContextWe need to secure our API endpoints with user authentication.
## ObjectiveImplement 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 NotesUse bcrypt for password hashing, JWT for tokens, and implement refresh token logic.
## Estimate5 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 workproject = {PROJECT_KEY} AND assignee = currentUser() AND status = "In Progress"
# Recent issuesproject = {PROJECT_KEY} AND created >= -7d
# High priority bugsproject = {PROJECT_KEY} AND type = Bug AND priority = High
# Epics without completionproject = {PROJECT_KEY} AND type = Epic AND status != Done
# Unassigned tasksproject = {PROJECT_KEY} AND assignee is EMPTY AND status = "To Do"
# Issues updated this weekproject = {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