atlassian-rest

Files (33)

• SKILL.md
• evals.json · evals/
• action-item-patterns.md · references/
• breakdown-examples.md · references/
• bug-report-templates.md · references/
• confluence-api.md · references/
• confluence-formatting.md · references/
• epic-templates.md · references/
• jira-api.md · references/
• jql-patterns.md · references/
• query-languages.md · references/
• report-templates.md · references/
• search-patterns.md · references/
• sync-mapping-guide.md · references/
• ticket-writing-guide.md · references/
• .gitignore · scripts/
• confluence-format.mjs · scripts/
• confluence.mjs · scripts/
• jira.mjs · scripts/
• package-lock.json · scripts/
• package.json · scripts/
• setup.mjs · scripts/
• sync-confluence-space.mjs · scripts/
• sync.mjs · scripts/
• test-format.mjs · scripts/
• capture-tasks-from-meeting-notes.md · workflows/
• create-confluence-document.md · workflows/
• generate-status-report.md · workflows/
• search-company-knowledge.md · workflows/
• spec-to-backlog.md · workflows/
• sync-bmad-documents.md · workflows/
• sync-confluence-space.md · workflows/
• triage-issue.md · workflows/

SKILL.md (first lines)

# 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

From bmad-labs/skills, MIT.

More from bmad-labs/skills