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

Jira Assistant Skill

This skill provides expert Jira operations using Atlassian MCP tools. It automatically detects workspace Jira configuration from context or prompts for project details.

Configuration Requirements

The skill requires the following configuration values to be available in your workspace context:

Required Values

• Project Key - The Jira project key (e.g., KAN, PROJ, DEV)
• Cloud ID - Your Atlassian Cloud ID (UUID format or site URL)
• URL - Your Atlassian site URL (e.g., https://example.atlassian.net/)

Optional Values

• Project Name - Human-readable project name
• Board URL - Link to your Jira board (optional, for convenience)

Where to Configure

The skill detects configuration from multiple sources, making it compatible with different IDEs and setups:

Option 1: Cursor Rules (.cursor/rules/jira-config.mdc)

If you're using Cursor, create a rule file:

---
alwaysApply: false
---

# Jira Project Configuration

This workspace uses the following Jira configuration:

- **Project Key:** YOUR_PROJECT_KEY
- **Cloud ID:** your-cloud-id-uuid-or-url
- **URL:** https://your-site.atlassian.net/
- **Project Name:** Your Project Name (optional)
- **Board URL:** https://your-site.atlassian.net/jira/software/projects/YOUR_PROJECT_KEY/boards/1 (optional)

Option 2: AGENTS.md

If you're using another IDE or prefer AGENTS.md, add the configuration there:

# Jira Configuration

- **Project Key:** YOUR_PROJECT_KEY
- **Cloud ID:** your-cloud-id-uuid-or-url
- **URL:** https://your-site.atlassian.net/
- **Project Name:** Your Project Name (optional)
- **Board URL:** https://your-site.atlassian.net/jira/software/projects/YOUR_PROJECT_KEY/boards/1 (optional)

Option 3: Other Context Sources

The skill will also detect configuration from:

• Workspace documentation files
• Project README files
• Any markdown files in your workspace that contain Jira configuration

Option 4: Interactive Prompt

If no configuration is found, the skill will:

1. Use MCP tools to discover available Jira projects 2. Prompt you to select your project 3. Store the selection for the current conversation

Configuration Detection Flow

When the skill is activated, it follows this detection order:

1. Check workspace context - Looks for Jira configuration in:

• .cursor/rules/jira-config.mdc (Cursor)
• AGENTS.md (any IDE)
• Other workspace documentation files

2. If not found - Uses MCP search to discover available projects

3. If still unclear - Prompts user to specify project key

4. Uses detected values - Applies configuration for all operations

Example Configuration

Here's a complete example configuration:

# Jira Project Configuration

- **Project Key:** KAN
- **Cloud ID:** d58e860b-469d-4463-8f46-684934a5a851
- **URL:** https://techleadsclub.atlassian.net/
- **Project Name:** Tech Leads Club
- **Board URL:** https://techleadsclub.atlassian.net/jira/software/projects/KAN/boards/1

Usage

Once configured, the skill automatically uses your project settings for:

• Searching issues
• Creating tasks, epics, and subtasks
• Updating issues
• Transitioning issue status
• Adding comments
• Querying with JQL

All operations will use your configured project key and cloud ID automatically.

Troubleshooting

Skill can't find configuration:

• Ensure your configuration file is in the workspace root or .cursor/rules/ directory
• Check that the file contains the required values (Project Key, Cloud ID, URL)
• Verify the format matches the examples above

Wrong project being used:

• Check your configuration file for the correct project key
• The skill uses the first valid configuration it finds
• You can override by specifying the project in your request

Configuration not detected:

• The skill will prompt you interactively if no configuration is found
• You can also specify project details directly in your request: "Create a task in PROJECT_KEY project"

Compatibility

This skill works with:

• Cursor IDE (via .cursor/rules/)
• Any IDE supporting AGENTS.md
• Any workspace with accessible configuration files
• Interactive mode (prompts for configuration)