mgajewskik/jira

Jira & Confluence

Natural language interaction with Jira and Confluence. Supports CLI and MCP backends.

Environment Variables

Use these environment variables as the skill's stable configuration interface. Keep these names unchanged unless you intentionally add an external compatibility layer.

Jira:

JIRA_URL=https://your-jira-instance.com
[email protected]
JIRA_PERSONAL_TOKEN=your_jira_token

# Optional default project scope (comma-separated)
JIRA_PROJECTS=PROJECT_A,PROJECT_B

Confluence:

CONFLUENCE_URL=https://your-confluence-instance.com
CONFLUENCE_PERSONAL_TOKEN=your_confluence_token

CLI compatibility:

# jira-cli often expects JIRA_API_TOKEN; keep this mapping outside the skill logic
export JIRA_API_TOKEN="$JIRA_PERSONAL_TOKEN"

Notes:

• Keep these variable names unchanged if you want consistent behavior across this skill, your shell setup, and any wrappers.
• If your Jira or Confluence backend expects different variable names or auth conventions, map them externally while preserving this interface.

Load references/setup.md for full setup instructions.

---

Backend Selection

Detection Order

1. Check CLI availability: which jira
2. Check MCP availability: Look for mcp-atlassian_jira_* and mcp-atlassian_confluence_* tools
3. If neither is available: guide the user to configure one of them

Backend Strengths

| Task | Best Backend | Why | |------|--------------|-----| | View single issue | CLI | Compact output, fast | | List my issues | CLI | Human-readable tables | | Search with JQL | MCP | Better JSON for processing | | Create issue | CLI | Simpler syntax | | Bulk operations | MCP | Batch support | | Transitions | MCP | Returns transition IDs | | Confluence (all) | MCP | CLI doesn't support Confluence | | Sprints/boards | Either | Similar capability |

Default:

• Use CLI for straightforward Jira read operations when it is available.
• Use MCP for Confluence, structured searches, transitions, and bulk operations.
• If both are available, prefer the backend that minimizes ambiguity and post-processing.

---

Project Context

CRITICAL: Scope queries to the user's intended projects.

1. If JIRA_PROJECTS is set, treat it as the default project scope.
2. For CLI: use -p PROJECT or --project PROJECT when scope matters.
3. For MCP: include project = KEY or project IN (...) in JQL when scope matters.
4. If the request could apply to multiple projects and scope is unclear, ask the user.
5. If the user clearly names a project, that overrides JIRA_PROJECTS.

Example - List my issues across projects:

# CLI approach (per project)
for proj in ${JIRA_PROJECTS//,/ }; do
  JIRA_API_TOKEN="$JIRA_PERSONAL_TOKEN" jira issue list -a$(jira me) -p "$proj" --plain
done

# MCP approach (single query)
jql: "assignee = currentUser() AND project IN (PROJECT_A, PROJECT_B) ORDER BY updated DESC"

---

Quick Reference (CLI)

Load references/cli.md for full CLI reference.

| Intent | Command | |--------|---------| | View issue | jira issue view KEY | | List my issues | jira issue list -a$(jira me) -p PROJECT | | My in-progress | jira issue list -a$(jira me) -s"In Progress" -p PROJECT | | Create issue | jira issue create -tType -s"Summary" -p PROJECT --no-input | | Transition | jira issue move KEY "Status" | | Assign to me | jira issue assign KEY $(jira me) | | Add comment | jira issue comment add KEY "Comment" | | Current sprint | jira sprint list --state active | | Who am I | jira me |

Always prefix CLI commands with: JIRA_API_TOKEN="$JIRA_PERSONAL_TOKEN"

---

Quick Reference (MCP Jira)

Load references/mcp-jira.md for full MCP Jira reference.

| Intent | Tool | |--------|------| | Search issues | mcp-atlassian_jira_search | | View issue | mcp-atlassian_jira_get_issue | | Create issue | mcp-atlassian_jira_create_issue | | Update issue | mcp-atlassian_jira_update_issue | | Get transitions | mcp-atlassian_jira_get_transitions | | Transition | mcp-atlassian_jira_transition_issue | | Add comment | mcp-atlassian_jira_add_comment | | List projects | mcp-atlassian_jira_get_all_projects | | Batch create | mcp-atlassian_jira_batch_create_issues |

---

Quick Reference (MCP Confluence)

Load references/mcp-confluence.md for full Confluence reference.

| Intent | Tool | |--------|------| | Search pages | mcp-atlassian_confluence_search | | Get page | mcp-atlassian_confluence_get_page | | Create page | mcp-atlassian_confluence_create_page | | Update page | mcp-atlassian_confluence_update_page | | Delete page | mcp-atlassian_confluence_delete_page | | Add comment | mcp-atlassian_confluence_add_comment | | Get children | mcp-atlassian_confluence_get_page_children |

---

Triggers

Jira:

• "jira", "ticket", "issue", "PROJ-123" (issue key pattern)
• "sprint", "backlog", "board"
• "create ticket", "move to done", "assign to me"
• "my tasks", "what am I working on"

Confluence:

• "confluence", "wiki", "documentation", "page"
• "create page", "update docs", "find in confluence"

---

Issue Key Detection

Pattern: [A-Z]+-[0-9]+ (e.g., PROJ-123, ABC-1)

When user mentions an issue key:

• CLI: jira issue view KEY
• MCP: mcp-atlassian_jira_get_issue(issue_key: "KEY")

---

Natural Language to JQL

Load references/jql.md for full JQL syntax.

| User says | JQL | |-----------|-----| | "my tickets" | assignee = currentUser() | | "my open tickets" | assignee = currentUser() AND status NOT IN (Done, Closed) | | "high priority bugs" | issuetype = Bug AND priority >= High | | "updated this week" | updated >= startOfWeek() | | "created by me" | reporter = currentUser() | | "in current sprint" | sprint in openSprints() | | "blocked tickets" | status = Blocked | | "unassigned" | assignee IS EMPTY |

Always add project filter when scope matters: AND project IN (PROJECT_A, PROJECT_B)

When JIRA_PROJECTS is not set, infer project scope from the request or ask the user.

---

Before Any Write Operation

Ask yourself:

1. What is the current state? Fetch the issue or page first. Do not assume status, assignee, fields, title, or content.
2. Who else is affected? Check watchers, linked issues, parent epics, page hierarchy, and related documentation.
3. Is this reversible? Transitions, deletions, and content edits may not have an easy undo path.
4. Do I have the right identifiers? Use exact issue keys, transition IDs, page IDs, and account IDs where required.

---

Workflow: View Issue

1. Detect issue key from user input
2. Use CLI: jira issue view KEY
3. Present summary, status, assignee, description
4. Offer actions: transition, comment, assign

---

Workflow: Create Issue

1. Gather: project, type, summary, description
2. If project not specified, ask (show JIRA_PROJECTS options)
3. Draft content, show to user
4. Get explicit approval
5. Create via CLI or MCP
6. Return issue key and link

---

Workflow: Transition Issue

1. Fetch current issue state
2. Get available transitions (MCP: `mcp-atlassian_jira_get_transitions`)
3. Show current status and available transitions
4. Get user approval for transition
5. Execute transition
6. Confirm new status

---

Workflow: Confluence Page

1. For search: use CQL via mcp-atlassian_confluence_search
2. For read: get page by ID or title+space
3. For create/update: draft content, show preview, get approval
4. Execute and return page URL

---

Safety Rules

ALWAYS

• Show command/tool call before executing
• Get explicit approval before any modification
• Fetch current state before updating
• Scope queries to user's projects
• Preserve original content when editing
• Verify the new state after applying changes
• Surface authentication or permission problems clearly

NEVER

• Transition without showing current status first
• Edit description without showing original
• Bulk modify without explicit approval per item
• Assume project - ask if ambiguous
• Use display names for MCP assignment (use account IDs)
• Assume transition names are universal across projects
• Use non-interactive CLI creation without confirming required fields

---

Approval Required

These operations require explicit user confirmation:

• Create issue
• Update issue (any field)
• Transition/move issue
• Delete issue
• Add/edit comment
• Create/update/delete Confluence page

For destructive or high-impact changes, show the exact proposed action before executing.

These can run without confirmation:

• View issue
• List issues
• Search (Jira or Confluence)
• Get transitions
• Get page content

---

Output Format

For user display: Human-readable tables and summaries

Example issue list:

| Key | Status | Summary | Priority |
|-----|--------|---------|----------|
| PROJ-123 | In Progress | Fix login bug | High |
| PROJ-124 | To Do | Add export feature | Medium |

For internal processing: Use MCP JSON responses

---

Error Handling

| Error | Cause | Resolution | |-------|-------|------------| | "No result found" | Wrong project scope | Check JIRA_PROJECTS, use -p flag | | 401 Unauthorized | Token expired/invalid | Regenerate JIRA_PERSONAL_TOKEN | | 403 Forbidden | No project access | Verify project permissions | | 404 Not Found | Issue doesn't exist | Check issue key | | JQL syntax error | Invalid query | Check JQL syntax in references/jql.md |

If neither CLI nor MCP is available, guide the user to configure one of them rather than guessing or simulating results.

---

Progressive Loading

Load references when:

• references/cli.md - Creating issues, complex CLI operations, troubleshooting CLI
• references/mcp-jira.md - Batch operations, transitions, linking issues
• references/mcp-confluence.md - Any Confluence operation beyond simple search
• references/jql.md - Complex search queries, JQL syntax questions
• references/setup.md - Initial setup, authentication issues

Do NOT load references for:

• Simple view/list operations
• Basic status checks
• Opening issues in browser