atlassian - SKILL.md Agent Skill

name: atlassian description: Load this skill when reading from or writing to Jira Cloud or Confluence Cloud — searching issues, fetching a specific Jira issue or Confluence page, listing or performing workflow transitions, creating/updating issues, commenting on issues, publishing or updating Confluence pages, or understanding the atlassian MCP tools.

Atlassian Skill — Jira and Confluence via pi atlassian-mcp

When to load

Load this skill when:

Searching Jira issues with JQL (e.g. "find all open bugs in project FOO").
Fetching a specific Jira issue by key (e.g. "get the details of FOO-123").
Creating or updating Jira issues from postmortem notes, investigation summaries, etc.
Adding a comment to a Jira issue.
Transitioning an issue through a workflow (e.g. "move FOO-123 to In Progress").
Looking up available workflow transitions for a Jira issue.
Searching Confluence pages with CQL.
Fetching a specific Confluence page by ID.
Publishing a new Confluence page from a markdown document.
Updating an existing Confluence page (fetch-edit-push pattern).

Integration: pi atlassian-mcp extension

Atlassian operations are performed via the pi atlassian-mcp extension — a TypeScript extension bundled with pi that connects to mcp.atlassian.com using OAuth PKCE. Use the MCP tools listed below; there is no separate command-line surface.

Authentication

Authentication is via OAuth PKCE (not API tokens). Tokens are stored in ~/.pi/agent/atlassian-mcp-oauth.json and refreshed automatically on expiry.

To log in or re-authenticate, run /login-atlassian inside a pi session. This opens a browser-based authorization flow.

The ATLASSIAN_SITE, ATLASSIAN_EMAIL, and ATLASSIAN_API_TOKEN environment variables are not used by the pi MCP extension and are not forwarded into agent sandboxes.

cloudId — single-site vs multi-site setup

Most Atlassian MCP tools require a cloudId parameter (UUID identifying your Atlassian site). How you handle this depends on how the host is configured:

Single-site setup (default cloud ID configured)

If nx.programs.prism.pi.atlassian.defaultCloudId is set in the NixOS config (exposed as ATLASSIAN_DEFAULT_CLOUD_ID), the extension automatically injects the default cloud ID into every tool call that omits it. In this setup:

Do not pass cloudId on tool calls — it is injected automatically.
Do not call getCloudId or getAccessibleAtlassianResources first — those round-trips are unnecessary.
Tool descriptions will mark cloudId as optional and document the default.

Example for thankyoupayroll.atlassian.net (cloudId 08986a80-a6ed-4480-ae2d-4a439d50d71b):

getJiraIssue(issueIdOrKey: "PLAT-182")
# cloudId is omitted — the default is injected automatically

Multi-site setup (no default configured)

If no default is configured, cloudId is required on every call. Discover valid cloud IDs with:

getAccessibleAtlassianResources()
# or
getCloudId()  # if you have a site link or only an issue key

Then pass the UUID explicitly on each tool call.

Available tools (31 tools via OAuth)

The extension exposes the full Jira and Confluence CRUD surface:

Identity / discovery

atlassianUserInfo — who am I
getAccessibleAtlassianResources — list sites

Jira

getJiraIssue — fetch an issue by key
searchJiraIssuesUsingJql — JQL search
createJiraIssue — file a new issue
editJiraIssue — update issue fields
addCommentToJiraIssue — comment on an issue
getTransitionsForJiraIssue — list available transitions (falls back to REST API if upstream returns empty)
transitionJiraIssue — move an issue to a new status by transition ID
transitionJiraIssueByName — move an issue to a new status by transition name (preferred; resolves name to ID automatically)
getJiraIssueRemoteIssueLinks — remote links
getVisibleJiraProjects — list projects
getJiraProjectIssueTypesMetadata — issue type metadata for a project
getJiraIssueTypeMetaWithFields — field metadata for a specific issue type
lookupJiraAccountId — resolve a user to an account ID
addWorklogToJiraIssue — log time
getIssueLinkTypes — list issue link types
createIssueLink — link two issues

Confluence

getConfluencePage — fetch a page by ID
searchConfluenceUsingCql — CQL search
getConfluenceSpaces — list spaces
getPagesInConfluenceSpace — list pages in a space
getConfluencePageFooterComments — footer comments
getConfluencePageInlineComments — inline comments
getConfluenceCommentChildren — comment threads
getConfluencePageDescendants — child pages
createConfluencePage — publish a new page
updateConfluencePage — update an existing page
createConfluenceFooterComment — add a footer comment
createConfluenceInlineComment — add an inline comment

General

search — cross-product search
fetch — fetch an arbitrary Atlassian URL

Common patterns

Jira: search and fetch

# Search for open issues in a project
searchJiraIssuesUsingJql(jql: "project = FOO AND status != Done ORDER BY created DESC", maxResults: 20)

# Fetch a specific issue
getJiraIssue(issueKey: "FOO-123")

Jira: create an issue

createJiraIssue(
  projectKey: "FOO",
  issueType: "Task",
  summary: "Investigate memory leak in worker pool",
  description: "## What happened\n\nSaw OOM errors in production...",
)

Jira: comment and transition

# Comment
addCommentToJiraIssue(issueKey: "FOO-123", comment: "Confirmed fixed in staging.")

# Transition by name (preferred — no need to look up transition IDs)
transitionJiraIssueByName(issueIdOrKey: "FOO-123", transitionName: "In Progress")

# Or: list transitions, then transition by ID
getTransitionsForJiraIssue(issueKey: "FOO-123")
transitionJiraIssue(issueKey: "FOO-123", transitionId: "31")

The transitionJiraIssueByName tool resolves the transition name case-insensitively and calls through to transitionJiraIssue automatically. If the name matches no available transition, it returns an error listing the available names. getJiraIssue also returns a transitions array so you can see available transitions alongside the issue data.

Lifecycle: when to transition a ticket

A Jira board reflects reality only when agents keep ticket state in sync with actual work. Transition tickets at the right moments so humans can trust the board at a glance.

Mandatory transitions

1. When work starts → transition to In Progress

As soon as you begin acting on a ticket — first commit, first PR draft, first substantive investigation that produces output — transition it to In Progress:

# You have been asked to action PLAT-123. Before your first commit:
transitionJiraIssueByName(issueIdOrKey: "PLAT-123", transitionName: "In Progress")
# Now begin the work.

2. When work completes → transition to the terminal state

Once the work is done — PR merged, doc published, change deployed — transition the ticket to its closed state:

# PR has been merged. Transition the ticket:
transitionJiraIssueByName(issueIdOrKey: "PLAT-123", transitionName: "Done")

The terminal state name varies by project workflow. Done is the default; if it is not available, call getTransitionsForJiraIssue (or read the transitions array returned by getJiraIssue) to find the correct closed state for this project — Closed, Resolved, Complete, or similar.

Read-only interactions — keep the state as-is

When you are reading a ticket purely for context — gathering background, summarising the issue, or evaluating whether to action it — the ticket state stays exactly as it is. Transition only when you actually begin or finish work.

Coordinator / worker boundary

The coordinator that files a ticket and spawns a worker leaves the ticket in its initial state — the worker owns the In Progress transition at the moment it starts. After the PR merges, the coordinator verifies the ticket reached a terminal state and transitions it if the worker has not already done so.

Blocked or handed-off tickets (judgement call)

If you escalate, hand off to a human, or otherwise pause on a ticket before completion, add a comment explaining the situation and optionally transition to a suitable intermediate state (Blocked, In Review, etc.) based on what is available in the project workflow.

Confluence: fetch-edit-push

# 1. Find the page
searchConfluenceUsingCql(cql: 'space = ENG AND title = "Architecture Overview"', limit: 1)

# 2. Fetch its body
getConfluencePage(pageId: "123456789")

# 3. Push an update
updateConfluencePage(
  pageId: "123456789",
  title: "Architecture Overview",
  body: "<updated markdown content>",
)

Output slimming

The pi atlassian-mcp extension applies the same field-drop sets as the prism MCP proxy, removing verbose metadata (expand, self, iconUrl, avatarUrls, renderedFields, operations, etc.) so tool outputs are compact enough to fit in context.

Troubleshooting

"Not logged in" / auth error: run /login-atlassian in your pi session to complete the OAuth flow.
Token expired: the extension refreshes tokens automatically on each session_start. If refresh fails, /login-atlassian again.
Permission error on a specific tool: some Atlassian tools require admin scopes. Check whether your account has the necessary Jira/Confluence permissions.
Debug logging: set ATLASSIAN_MCP_DEBUG=1 in the environment to get MCP request/response logs on stderr.