setup

name

setup

description

This skill should be used when the user wants to "connect to Jira", "connect to Confluence", "authenticate with Atlassian", "set up Jira/Confluence access", "use my Atlassian API token", or before running any Jira or Confluence REST API call. Establishes Atlassian Cloud Basic auth (email + API token) and the global conventions both APIs share (base paths, headers, Jira startAt/maxResults vs Confluence cursor pagination, ADF/storage body formats, accountId).

Atlassian Setup & Authentication

Establish access to an Atlassian Cloud site and learn the conventions every other call depends on. Do this once per session before any Jira or Confluence operation. One API token authenticates both products on the same site.

Environment variables

The user sets these in their shell or repo .env. Read them — never hardcode or print the token.

Variable	Required	Meaning
ATLASSIAN_SITE_URL	yes	Cloud site root, e.g. https://your-domain.atlassian.net. No trailing path — do not append /rest or /wiki here.
ATLASSIAN_EMAIL	yes	Atlassian account email. Used as the username half of HTTP Basic auth.
ATLASSIAN_API_TOKEN	yes	API token minted at https://id.atlassian.com/manage-profile/security/api-tokens. Used as the password half. Treat it like a password — never echo or commit it.

If ATLASSIAN_SITE_URL is missing, ask the user for it. Normalize the trailing slash with ${ATLASSIAN_SITE_URL%/} and build the two product bases from it:

JIRA="${ATLASSIAN_SITE_URL%/}/rest/api/3"      # Jira Cloud platform REST v3
CONF="${ATLASSIAN_SITE_URL%/}/wiki/api/v2"     # Confluence Cloud REST v2 (note the /wiki prefix)

Step 1 — Verify access (one call per product)

# Jira: who am I (confirms the token works on Jira)
curl -s -u "${ATLASSIAN_EMAIL}:${ATLASSIAN_API_TOKEN}" -H "Accept: application/json" \
  "${ATLASSIAN_SITE_URL%/}/rest/api/3/myself" | jq '{accountId, displayName, emailAddress}'

# Confluence: list one space (confirms the /wiki/api/v2 base + token)
curl -s -u "${ATLASSIAN_EMAIL}:${ATLASSIAN_API_TOKEN}" -H "Accept: application/json" \
  "${ATLASSIAN_SITE_URL%/}/wiki/api/v2/spaces?limit=1" | jq '.results[0] | {id, key, name}'

A 200 with your account on /myself confirms the Jira token; a space object confirms Confluence. A 401 means a bad email/token. A 404 on the Confluence call almost always means the base path is missing the /wiki prefix.

Global conventions (apply to every call)

Internalize these once so individual operations stay short.

• Auth — HTTP Basic. Send -u "${ATLASSIAN_EMAIL}:${ATLASSIAN_API_TOKEN}" on every request (curl base64-encodes it). Always add -H "Accept: application/json"; add -H "Content-Type: application/json" whenever you send a JSON body (POST/PUT). The password is the API token, never the account password.
• REST by noun, real verbs. Unlike RPC-style APIs, these use HTTP methods and path params: GET to read, POST to create, PUT to update, DELETE to remove. The resource id lives in the path (e.g. /issue/PROJ-123, /pages/12345).
• Jira rich text is ADF (JSON), not markdown. description, comment body, and other rich-text fields on Jira v3 are Atlassian Document Format documents, not plain strings. The minimal paragraph:

  {"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Hello from the API"}]}]}
  

  A plain string in those fields returns 400.
• Confluence bodies carry a . Use (XHTML storage format) or (ADF). On , you must send the (current + 1) — Confluence uses optimistic locking, so fetch the current version first.

Next steps

• Everyday Jira work (create issue, JQL search, transition, comment, assign, report) → use the jira-operations skill.
• Everyday Confluence work (create/update pages, spaces, comments, labels) → use the confluence-operations skill.
• The full endpoint catalog of every resource → load the api-reference skill and open the relevant references/jira/*.md or references/confluence/*.md file (or grep the bundled *-openapi-*.json specs).
• When a call fails → use the troubleshoot skill.