Stats
Actions
Tags
From bmad-skills
Interact with Atlassian Jira and Confluence via REST APIs. Create, edit, search, and transition Jira issues; read and write Confluence pages. No MCP server needed.
How this skill is triggered — by the user, by Claude, or both
Slash command
/bmad-skills:atlassian-restThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Portable Jira & Confluence integration via REST APIs. Works in any agent environment with Node.js 18+ — zero dependencies, no MCP server required.
evals/evals.jsonreferences/action-item-patterns.mdreferences/breakdown-examples.mdreferences/bug-report-templates.mdreferences/confluence-api.mdreferences/confluence-formatting.mdreferences/epic-templates.mdreferences/jira-api.mdreferences/jql-patterns.mdreferences/query-languages.mdreferences/report-templates.mdreferences/search-patterns.mdreferences/sync-mapping-guide.mdreferences/ticket-writing-guide.mdscripts/confluence-format.mjsscripts/confluence.mjsscripts/jira.mjsscripts/package-lock.jsonscripts/package.jsonscripts/setup.mjsPortable Jira & Confluence integration via REST APIs. Works in any agent environment with Node.js 18+ — zero dependencies, no MCP server required.
<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:
node <skill-path>/scripts/setup.mjs
If it fails, guide the user through the setup — the script prints step-by-step instructions.
| Variable | Description | Example |
|---|---|---|
ATLASSIAN_API_TOKEN | API token | (generated at Atlassian) |
ATLASSIAN_EMAIL | Account email | [email protected] |
ATLASSIAN_DOMAIN | Atlassian site domain | company.atlassian.net |
When the user asks you to do something with Jira or Confluence, follow these principles:
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.
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.
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.
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>.
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.
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.
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.
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.
Script: node <skill-path>/scripts/jira.mjs <command> [args]
jira.mjs search 'project = PROJ AND status = "In Progress"' --max 20
jira.mjs get PROJ-123
jira.mjs get PROJ-123 --fields summary,status,assignee
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.
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
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
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.
jira.mjs projects # List all visible projects
jira.mjs issue-types PROJ # List issue types for a project
jira.mjs link-types # List available link types first
jira.mjs link PROJ-1 PROJ-2 --type "relates to"
jira.mjs lookup-user "john" # Returns account ID needed for --assignee
jira.mjs worklog PROJ-123 --time 2h --comment "Code review"
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.
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.
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
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.
The field mapping JSON (memory/jira-<docType>-field-mapping.json) supports an instructions field for additional agent guidance:
{
"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.
sync.mjs batch # Scan all linked docs and report status
Script: node <skill-path>/scripts/confluence.mjs <command> [args]
confluence.mjs search 'type = page AND text ~ "architecture"' --max 10
confluence.mjs get-page 12345
confluence.mjs get-page 12345 --format view
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.
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.
confluence.mjs comment 12345 "Reviewed and approved"
# For long comments, use a file:
confluence.mjs comment 12345 --body-file /tmp/comment.md
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.
# 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.
confluence.mjs spaces --max 20
confluence.mjs descendants 12345 # Get child pages
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.
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> |
storageToMarkdown HandlesThe converter handles real-world Confluence storage format patterns including:
<details><summary> collapsible sections, jira references, view-file → attachment links, toc/children (stripped)ac:structured-macro types have their body content preserved (not silently dropped)<colgroup>, <tbody>, <thead> wrappers stripped; attributes on <table>, <tr>, <th>, <td> handled<ac:task-list> with <ac:task-id> → markdown checkboxes with filename as fallback alt text; parentheses and spaces in filenames URL-encodedArray<string> preserved inside fenced blocks’, “, →, , numeric {)\n\n around headings, images, lists, <hr>, tables, code blockslocal-id, data-layout, breakoutWidth, etc.)**text ** → **text**)For most use cases, use the built-in sync script directly:
node <skill-path>/scripts/sync-confluence-space.mjs --root <pageId> --output ./docs
For custom sync scripts, import storageToMarkdown and follow this pattern:
import { storageToMarkdown } from '<skill-path>/scripts/confluence-format.mjs';
// Fetch page via Confluence v2 API
const page = await apiGet(`/wiki/api/v2/pages/${pageId}`, { 'body-format': 'storage' });
const html = page.body.storage.value;
// Convert to markdown
let markdown = storageToMarkdown(html);
// Add linked title using page._links.base + page._links.webui
const pageUrl = `${page._links.base}${page._links.webui}`;
markdown = `# [${page.title}](${pageUrl})\n\n${markdown}`;
Key gotchas discovered in production use:
_links.webui is a relative path (e.g., /spaces/BTH/pages/123/Title). Combine with _links.base (e.g., https://company.atlassian.net/wiki) for the full URL — do NOT use env.domain + _links.webui directly (missing /wiki prefix)..getChildrenTree() (recursive children API) to build the tree, then decide per-node: pages with children → directory/index.md, leaf pages → flat PageName.md.assets/imgs/ and assets/pdfs/ directory. Use depth-aware relative paths (../assets/imgs/ at depth 1, ../../assets/imgs/ at depth 2, etc.).) and file attachment links ([filename](filename)) to local paths — Confluence view-file macros produce regular links, not image references.local-id, breakoutWidth, data-layout) to most HTML tags. Any regex matching tags must use [^>]* for optional attributes.node <skill-path>/scripts/test-format.mjs
100+ tests covering forward conversion, reverse conversion, round-trip preservation, block element spacing, code block protection, image URL encoding, entity decoding, expand macros with nested content, view-file macros, unknown macro catch-all, and attribute tolerance on HTML tags.
For complex multi-step operations that require user interaction across several turns, read the corresponding workflow file and follow its step-by-step process. For simple one-shot commands, use the operations sections above directly.
| Workflow | When to use | File |
|---|---|---|
| Capture Tasks from Meeting Notes | User provides meeting notes and wants Jira tasks created from action items | workflows/capture-tasks-from-meeting-notes.md |
| Generate Status Report | User wants a project status report, sprint summary, or weekly update | workflows/generate-status-report.md |
| Search Company Knowledge | User wants to find information across Confluence pages and Jira issues | workflows/search-company-knowledge.md |
| Spec to Backlog | User has a Confluence spec and wants it broken into an Epic + child tickets | workflows/spec-to-backlog.md |
| Triage Issue | User reports a bug and wants duplicate checking before filing | workflows/triage-issue.md |
| Create Confluence Document | User wants a professional Confluence page with macros, images, and structured formatting | workflows/create-confluence-document.md |
| Sync BMAD Documents | User wants to sync local BMAD docs (epics, tech specs, PRDs, architecture) with Jira or Confluence, or link a document to a ticket/page | workflows/sync-bmad-documents.md |
| Sync Confluence Space | User wants to download an entire Confluence space to local markdown files with hierarchy, images, and linked titles | workflows/sync-confluence-space.md |
| Error | Likely Cause | Resolution |
|---|---|---|
401 Unauthorized | Bad or expired API token | Regenerate at Atlassian security settings |
403 Forbidden | Insufficient permissions | Check project/space permissions for the user's account |
404 Not Found | Wrong issue key, page ID, or domain | Verify the resource exists and ATLASSIAN_DOMAIN is correct |
429 Too Many Requests | Rate limited | Wait briefly and retry; reduce batch sizes |
| Missing env vars | Not configured | Run node <skill-path>/scripts/setup.mjs |
Load these as needed — don't read them all upfront:
| Reference | When to consult |
|---|---|
references/jira-api.md | Need details on Jira API endpoints or request shapes |
references/confluence-api.md | Need details on Confluence API endpoints or storage format |
references/confluence-formatting.md | Building professional pages with macros, layouts, images, and document templates |
references/query-languages.md | Writing JQL or CQL queries |
references/jql-patterns.md | Need common JQL patterns for reports, searches, filters |
references/action-item-patterns.md | Parsing meeting notes for action items |
references/report-templates.md | Generating status reports |
references/bug-report-templates.md | Creating well-structured bug reports |
references/search-patterns.md | Multi-source search strategies |
references/epic-templates.md | Writing epic descriptions |
references/ticket-writing-guide.md | Writing clear ticket summaries and descriptions |
references/breakdown-examples.md | Breaking specs into stories and tasks |
references/sync-mapping-guide.md | Before first document sync, when mapping fields fail, or configuring custom field mappings |
npx claudepluginhub bmad-labs/skills --plugin bmad-skillsProvides templates for Confluence docs like TDD, ADR, API, runbooks, release notes. Covers CQL queries and Jira linking for engineering teams managing technical documentation.
Generates project status reports from Jira issues using JQL, categorizes by status/priority, analyzes blockers/progress, formats for executives/teams, and publishes to Confluence.
Read, search, create, update, move, delete, and convert Confluence pages and attachments using confluence-cli from the terminal or agents.