atlassian-rest
Interact with Atlassian Jira and Confluence using REST APIs — no MCP server needed. Use this skill whenever the user mentions Jira, Confluence, Atlassian, tickets, issues, sprints, backlogs, epics, stories, or any project management task that involves creating/editing/searching/transitioning Jira issues, writing or reading Confluence pages, generating status reports, triaging bugs, converting specs to backlogs, capturing tasks from meeting notes, searching company knowledge, syncing local BMAD documents with Jira or Confluence, pushing docs to Jira, pulling from Jira, linking documents to tickets, downloading Confluence spaces to local markdown, or converting between Confluence storage format and markdown. Also trigger when the user says things like "move that ticket to done", "what's the status of PROJ-123", "create a bug for X", "search our wiki for Y", "file a ticket", "check for duplicates", "write a status update", "break this spec into stories", "sync this doc", "push to jira", "pull from jira", "sync t
Source facts
- Repository
- bmad-labs/skills
- Last source activity
- March 19, 2026 at 09:22
- Detected SKILL.md language
- English
- Stars
- 15
- Forks
- 4
Install options
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Review the source files
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
File Explorer
33 filesShowing SKILL.md
SKILL.md
Source instructions · Read-only preview- name
- atlassian-rest
- description
- Interact with Atlassian Jira and Confluence using REST APIs — no MCP server needed. Use this skill whenever the user mentions Jira, Confluence, Atlassian, tickets, issues, sprints, backlogs, epics, stories, or any project management task that involves creating/editing/searching/transitioning Jira issues, writing or reading Confluence pages, generating status reports, triaging bugs, converting specs to backlogs, capturing tasks from meeting notes, searching company knowledge, syncing local BMAD documents with Jira or Confluence, pushing docs to Jira, pulling from Jira, linking documents to tickets, downloading Confluence spaces to local markdown, or converting between Confluence storage format and markdown. Also trigger when the user says things like "move that ticket to done", "what's the status of PROJ-123", "create a bug for X", "search our wiki for Y", "file a ticket", "check for duplicates", "write a status update", "break this spec into stories", "sync this doc", "push to jira", "pull from jira", "sync to confluence", "link this to jira", "sync my epics", "download confluence pages", "sync confluence space", "convert confluence to markdown", or "pull docs from confluence". If there is even a chance the user wants to interact with Jira or Confluence, use this skill.
# Atlassian REST API Skill
Portable Jira & Confluence integration via REST APIs. Works in any agent environment with Node.js 18+ — zero dependencies, no MCP server required.
## First-Use Setup
`<skill-path>` throughout this document refers to the directory where this skill is installed. Resolve it from the skill invocation context (e.g., the path shown by `claude plugin list` or the skill's directory in `.claude/plugins/`).
Before any operation, verify the user has credentials configured. Run:
```bash
node <skill-path>/scripts/setup.mjs
```
If it fails, guide the user through the setup — the script prints step-by-step instructions.
### Required Environment Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `ATLASSIAN_API_TOKEN` | API token | *(generated at Atlassian)* |
| `ATLASSIAN_EMAIL` | Account email | `user@company.com` |
| `ATLASSIAN_DOMAIN` | Atlassian site domain | `company.atlassian.net` |
---
## How to Use This Skill
When the user asks you to do something with Jira or Confluence, follow these principles:
1. **Resolve ambiguity first.** If the user says "create a ticket" but hasn't specified a project, run `node <skill-path>/scripts/jira.mjs projects` to list available projects, then ask which one. Same for issue types — run `node <skill-path>/scripts/jira.mjs issue-types <projectKey>` if unsure.
2. **Confirm before mutating.** Before creating issues, transitioning tickets, or publishing Confluence pages, show the user what you're about to do and get confirmation. Read operations (search, get, list) don't need confirmation.
3. **Never delete.** This skill does not support delete operations (issues, pages, attachments, boards, projects, accounts, etc.). If the user asks to delete something, direct them to the Atlassian web UI. This restriction is intentional and must not be bypassed.
4. **Compose operations naturally.** Many user requests require multiple script calls. For example, "assign PROJ-123 to Sarah" requires: (a) `lookup-user "Sarah"` to get the account ID, then (b) `edit PROJ-123 --assignee <accountId>`.
5. **Prefer sync.mjs for document-based operations.** When creating Jira issues from a local markdown file (story docs, specs, epics), use `sync.mjs` instead of raw `jira.mjs create` — it handles field mapping, link tracking, and sync state automatically. See the Document Sync Operations section below for details. Only use `jira.mjs create` for ad-hoc issues not backed by a local document.
6. **Use workflows for complex tasks.** If the user's request matches one of the workflows below, read the corresponding file and follow its step-by-step process.
7. **Read reference docs when needed.** Before writing JQL/CQL queries, consult `references/query-languages.md`. Before creating tickets, consult `references/ticket-writing-guide.md`. The reference docs exist to help you produce high-quality output — use them.
### Passing Long Content to Scripts
For descriptions, comments, or page bodies longer than ~200 characters or containing special
characters (backticks, quotes, `$`, newlines), **write the content to a temp file** and use the
file-based flag:
| Inline Flag | File Flag | Commands |
|-------------|-----------|----------|
| `--description "text"` | `--description-file /tmp/desc.md` | jira create, jira edit |
| `<body>` (positional) | `--body-file /tmp/body.md` | jira comment, confluence comment |
| `--body "text"` | `--body-file /tmp/body.md` | confluence create-page, update-page |
| `--comment "text"` | `--comment-file /tmp/comment.md` | jira worklog |
Write **plain markdown** to the file — scripts handle conversion to ADF (Jira) or storage format (Confluence) automatically. Prefer file-based input to avoid shell escaping issues.
---
## Jira Operations
Script: `node <skill-path>/scripts/jira.mjs <command> [args]`
### Search Issues
```bash
jira.mjs search 'project = PROJ AND status = "In Progress"' --max 20
```
### Get Issue Details
```bash
jira.mjs get PROJ-123
jira.mjs get PROJ-123 --fields summary,status,assignee
```
### Create Issue
```bash
jira.mjs create --project PROJ --type Task --summary "Implement feature X" \
--description "Details here" --priority High --assignee <accountId> \
--labels "backend,urgent" --components "API,Auth"
jira.mjs create --project PROJ --type Story --summary "User login" --parent PROJ-100
# For long descriptions, use a file:
jira.mjs create --project PROJ --type Task --summary "Feature X" \
--description-file /tmp/desc.md --priority High
```
When creating child stories under an Epic, include `--priority Medium` unless the user specifies a different priority.
### Edit Issue
```bash
jira.mjs edit PROJ-123 --summary "Updated title" --priority Medium
jira.mjs edit PROJ-123 --labels "backend,v2" --components "API"
# For long descriptions, use a file:
jira.mjs edit PROJ-123 --description-file /tmp/desc.md
```
### Comments
```bash
jira.mjs comment PROJ-123 "Fixed in PR #456"
# For long comments, use a file:
jira.mjs comment PROJ-123 --body-file /tmp/comment.md
```
### Transitions (move ticket status)
```bash
jira.mjs transitions PROJ-123 # List available transitions first
jira.mjs transition PROJ-123 31 # Then transition by ID
```
Always list transitions first to get the correct ID — don't guess.
### Projects & Issue Types
```bash
jira.mjs projects # List all visible projects
jira.mjs issue-types PROJ # List issue types for a project
```
### Issue Links
```bash
jira.mjs link-types # List available link types first
jira.mjs link PROJ-1 PROJ-2 --type "relates to"
```
### User Lookup
```bash
jira.mjs lookup-user "john" # Returns account ID needed for --assignee
```
### Worklog
```bash
jira.mjs worklog PROJ-123 --time 2h --comment "Code review"
```
---
## Document Sync Operations
Script: `node <skill-path>/scripts/sync.mjs <command> [args]`
When creating Jira/Confluence items from local markdown documents, prefer sync.mjs over raw jira.mjs/confluence.mjs — it auto-updates the source document with links and maintains sync state.
### Setup Field Mapping (first time per doc type)
```bash
sync.mjs setup-mapping --type story --sample PROJ-200 # Auto-detect fields from existing ticket
sync.mjs setup-mapping --type epic --sample PROJ-100 # Creates memory/jira-epic-field-mapping.json
```
Field mappings are stored in `<skill-path>/memory/` and define how markdown sections map to Jira fields. See `references/sync-mapping-guide.md` for the full schema.
### Link & Create from Document
```bash
sync.mjs link <file> --type story --project PROJ --create # Create Jira issue + update doc
sync.mjs link <file> --type epic --project PROJ --create # Create epic + child stories
sync.mjs link <file> --type story --ticket PROJ-123 # Link to existing ticket
```
### Push/Pull Changes
```bash
sync.mjs push <file> # Push local changes to Jira/Confluence
sync.mjs push <file> --delete-orphans # Push + prompt to delete orphaned Sub-* subtasks
sync.mjs pull <file> # Pull remote changes to local
sync.mjs diff <file> # Show per-section diff
sync.mjs status <file> # Show sync status
```
When `push` reports orphaned subtasks (sections removed from local doc), ask the user if they want to delete them, then run with `--delete-orphans`. Only `Sub-*` issue types can be deleted — parent issues are skipped.
### Custom Instructions in Mapping Config
The field mapping JSON (`memory/jira-<docType>-field-mapping.json`) supports an `instructions` field for additional agent guidance:
```json
{
"instructions": "Always set priority to High. Add label 'team-alpha'. Use Sub-Imp type for child items."
}
```
When present, instructions are printed to stdout during `push` and `link` operations so the calling agent can follow them.
### Batch Operations
```bash
sync.mjs batch # Scan all linked docs and report status
```
---
## Confluence Operations
Script: `node <skill-path>/scripts/confluence.mjs <command> [args]`
### Search Pages
```bash
confluence.mjs search 'type = page AND text ~ "architecture"' --max 10
```
### Get Page
```bash
confluence.mjs get-page 12345
confluence.mjs get-page 12345 --format view
```
### Create Page
```bash
confluence.mjs create-page --space TEAM --title "Sprint Report" --body "Report content"
confluence.mjs create-page --space TEAM --title "Sub Page" \
--body "<h2>Heading</h2><p>Content</p>" --parent 12345
confluence.mjs create-page --space TEAM --title "Full Doc" --body-file /tmp/body.md
```
The `--body` flag accepts **markdown** (recommended), plain text, or raw HTML storage format (if it starts with `<`). The script automatically converts markdown to Confluence storage format — headings, lists, tables, and code blocks (converted to `ac:structured-macro ac:name="code"` with language detection) are all handled. Prefer writing markdown and letting the script handle conversion rather than manually constructing storage format XHTML. Use `--body-file` for long documents that would exceed shell argument limits.
### Update Page
```bash
confluence.mjs update-page 12345 --title "Updated Title" --body "New content"
confluence.mjs update-page 12345 --title "Updated Title" --body-file /tmp/body.md
```
Version is auto-incremented — no need to track it manually. Use `--body-file` for large page updates.
### Comments
```bash
confluence.mjs comment 12345 "Reviewed and approved"
# For long comments, use a file:
confluence.mjs comment 12345 --body-file /tmp/comment.md
```
### Attachments
```bash
confluence.mjs attach 12345 ./screenshot.png --comment "Architecture diagram"
confluence.mjs list-attachments 12345 --max 10
```
Use `attach` to upload local files (images, PDFs, etc.) to a page. After uploading, embed images in the page body using `<ac:image><ri:attachment ri:filename="screenshot.png" /></ac:image>` — see `references/confluence-formatting.md` for sizing guidelines.
### Sync Confluence Space to Local Markdown
```bash
# Download an entire page tree to local markdown with attachments
node <skill-path>/scripts/sync-confluence-space.mjs --root <pageId> --output ./docs
# Preview without writing files
node <skill-path>/scripts/sync-confluence-space.mjs --root <pageId> --output ./docs --dry-run
# Skip attachment downloads (faster, markdown only)
node <skill-path>/scripts/sync-confluence-space.mjs --root <pageId> --output ./docs --skip-attachments
```
Downloads an entire Confluence page tree to local markdown files with hierarchy, images, and linked titles. Rewrites both image references and file attachment links to point to local assets. See `workflows/sync-confluence-space.md` for full details and customization options.
### Spaces & Navigation
```bash
confluence.mjs spaces --max 20
confluence.mjs descendants 12345 # Get child pages
```
---
## Format Conversion Utilities
Script: `<skill-path>/scripts/confluence-format.mjs`
This module provides bidirectional markdown ↔ Confluence storage format conversion. It's used internally by `confluence.mjs` but can also be imported directly for custom sync scripts.
### Exported Functions
```js
import { markdownToStorage, storageToMarkdown, htmlInlineToMarkdown } from '<skill-path>/scripts/confluence-format.mjs';
```
| Function | Direction | Use case |
|----------|-----------|----------|
| `markdownToStorage(md)` | Markdown → XHTML | Publishing to Confluence (auto-used by `confluence.mjs --body-file`) |
| `storageToMarkdown(html)` | XHTML → Markdown | Downloading/syncing Confluence pages to local markdown files |
| `htmlInlineToMarkdown(html)` | Inline HTML → Markdown | Converting snippets (table cells, list items) that may contain `<strong>`, `<em>`, `<a>`, `<code>` |
### What `storageToMarkdown` Handles
The converter handles real-world Confluence storage format patterns including:
- **Structured macros**: code blocks (with/without language), panels (info/tip/warning/note → GitHub alerts), expand → `<details><summary>` collapsible sections, jira references, view-file → attachment links, toc/children (stripped)
- **Unknown macros**: Any unrecognized `ac:structured-macro` types have their body content preserved (not silently dropped)
- **Tables**: `<colgroup>`, `<tbody>`, `<thead>` wrappers stripped; attributes on `<table>`, `<tr>`, `<th>`, `<td>` handled
- **Task lists**: `<ac:task-list>` with `<ac:task-id>` → markdown checkboxes
- **Images**: URL and attachment images → `` with filename as fallback alt text; parentheses and spaces in filenames URL-encoded
- **Code blocks**: Protected from HTML tag stripping via placeholder system — generic types like `Array<string>` preserved inside fenced blocks
- **Expand/collapsible bodies**: Full content support inside expand macros — code blocks, images, tables, panels, task lists, and nested macros all convert correctly
- **Entities**: Full HTML entity decoding (`’`, `“`, `→`, ` `, numeric `{`)
- **Block separation**: `\n\n` around headings, images, lists, `<hr>`, tables, code blocks
- **Attribute tolerance**: All HTML tag regexes accept optional attributes (handles Confluence's `local-id`, `data-layout`, `breakoutWidth`, etc.)
- **Bold/italic cleanup**: Trailing spaces inside markers fixed (`**text **` → `**text**`)
- **Stray angle brackets**: Escaped outside code blocks to prevent markdown renderer confusion
### Syncing a Confluence Space
For most use cases, use the built-in sync script directly:
```bash
View on GitHubThis SKILL.md is very large, so SkillsMP previews the first section here. View on GitHub
