atlassian-rest

Atlassian REST API スキル

REST API を介した、持ち運び可能な Jira と Confluence の連携です。Node.js 18 以降が動作するあらゆるエージェント環境で利用でき、依存関係はなく、MCP サーバーも不要です。

初回セットアップ

このドキュメント全体で使われている <skill-path> は、このスキルがインストールされているディレクトリを指します。スキルの呼び出しコンテキスト（例：claude plugin list に表示されるパス、または .claude/plugins/ 内のスキルのディレクトリ）から特定してください。

操作を行う前に、ユーザーの認証情報が設定されていることを確認してください。次を実行します。

node <skill-path>/scripts/setup.mjs

失敗した場合は、セットアップを案内してください。スクリプトに手順が表示されます。

必須環境変数

変数	説明	例
ATLASSIAN_API_TOKEN	API トークン	(Atlassian で生成)
ATLASSIAN_EMAIL	アカウントのメールアドレス	[email protected]
ATLASSIAN_DOMAIN	Atlassian サイトのドメイン	company.atlassian.net

---

このスキルの使い方

ユーザーから Jira または Confluence での操作を依頼された場合は、次の原則に従ってください。

1. まず曖昧さを解消します。 ユーザーが「チケットを作成して」と依頼したものの、プロジェクトを指定していない場合は、node <skill-path>/scripts/jira.mjs projects を実行して利用可能なプロジェクトを一覧表示し、どのプロジェクトかを尋ねます。課題タイプが不明な場合も同様に、node <skill-path>/scripts/jira.mjs issue-types <projectKey> を実行します。

2. 変更を加える前に確認します。 課題の作成、チケットのステータス遷移、Confluence ページの公開を行う前に、実行しようとしている内容をユーザーに示し、確認を得てください。読み取り操作（検索、取得、一覧表示）には確認は不要です。

3. 削除は絶対に行いません。 このスキルでは、課題、ページ、添付ファイル、ボード、プロジェクト、アカウントなどの削除操作はサポートしていません。ユーザーから削除を依頼された場合は、Atlassian の Web UI を案内してください。この制限は意図的なものであり、回避してはいけません。

4. 複数の操作を自然に組み合わせます。 ユーザーの依頼の多くは、スクリプトを複数回呼び出す必要があります。たとえば、「PROJ-123 を Sarah に割り当てて」という依頼では、（a）lookup-user "Sarah" でアカウント ID を取得し、（b）edit PROJ-123 --assignee <accountId> を実行します。

5. ドキュメントベースの操作には sync.mjs を優先します。 ローカルの Markdown ファイル（ストーリードキュメント、仕様書、エピック）から Jira 課題を作成する場合は、jira.mjs create を直接使うのではなく、sync.mjs を使ってください。フィールドのマッピング、リンクの追跡、同期状態の管理が自動で行われます。詳細は、以下の「ドキュメント同期の操作」セクションを参照してください。ローカルドキュメントを元にしない単発の課題に限り、jira.mjs create を使用してください。

6. 複雑なタスクにはワークフローを使用します。 ユーザーの依頼が以下のワークフローのいずれかに該当する場合は、対応するファイルを読み、その手順に従ってください。

7. 必要に応じてリファレンスドキュメントを読みます。 JQL／CQL クエリを書く前に references/query-languages.md を確認してください。チケットを作成する前に references/ticket-writing-guide.md を確認してください。リファレンスドキュメントは、質の高い出力を作成するために用意されています。活用してください。

長いコンテンツをスクリプトに渡す

説明、コメント、ページ本文が約 200 文字を超える場合、または特殊文字（バッククォート、引用符、$、改行）を含む場合は、内容を一時ファイルに書き込み、ファイル用フラグを使用してください。

インラインフラグ	ファイル用フラグ	コマンド
--description "text"	--description-file /tmp/desc.md	jira create、jira edit
<body>（位置引数）	--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

ファイルにはプレーンな Markdownを書き込んでください。スクリプトが ADF（Jira）またはストレージ形式（Confluence）への変換を自動で処理します。シェルのエスケープに関する問題を避けるため、ファイルからの入力を優先してください。

---

Jira の操作

スクリプト：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

エピックの下に子ストーリーを作成するときは、ユーザーが別の優先度を指定していない限り、--priority Medium を含めてください。

課題の編集

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

正しい ID を取得するため、必ず最初にトランジションを一覧表示してください。推測してはいけません。

プロジェクトと課題タイプ

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"

---

ドキュメント同期操作

スクリプト：node <skill-path>/scripts/sync.mjs <command> [args]

ローカルの Markdown ドキュメントから Jira／Confluence の項目を作成するときは、生の jira.mjs／confluence.mjs より sync.mjs を優先してください。sync.mjs はソースドキュメントをリンクで自動更新し、同期状態を維持します。

フィールドマッピングの設定（ドキュメントタイプごとに初回のみ）

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

フィールドマッピングは <skill-path>/memory/ に保存され、Markdown のセクションを Jira のフィールドにどのように対応付けるかを定義します。スキーマ全体については、references/sync-mapping-guide.md を参照してください。

ドキュメントからリンクして作成

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

push が孤立したサブタスク（ローカルドキュメントからセクションが削除されたもの）を報告した場合は、削除するかユーザーに確認してから、--delete-orphans を付けて実行してください。削除できるのは Sub-* の課題タイプのみです。親課題はスキップされます。

マッピング設定のカスタム指示

フィールドマッピング JSON（memory/jira-<docType>-field-mapping.json）では、追加のエージェント向けガイダンスとして instructions フィールドを使用できます。

{
  "instructions": "Always set priority to High. Add label 'team-alpha'. Use Sub-Imp type for child items."
}

このフィールドがある場合、push と link の操作中に指示が標準出力に表示されるため、呼び出し元のエージェントはそれに従うことができます。

一括操作

sync.mjs batch                # Scan all linked docs and report status

---

Confluence 操作

スクリプト：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

--body フラグは Markdown（推奨）、プレーンテキスト、または生の HTML ストレージ形式（< で始まる場合）を受け付けます。スクリプトは Markdown を Confluence ストレージ形式に自動変換します。見出し、リスト、表、コードブロック（言語を検出し、ac:structured-macro ac:name="code" に変換）をすべて処理します。ストレージ形式の XHTML を手動で組み立てるのではなく、Markdown を記述して変換をスクリプトに任せてください。シェル引数の制限を超える長いドキュメントには --body-file を使用してください。

ページの更新

confluence.mjs update-page 12345 --title "Updated Title" --body "New content"
confluence.mjs update-page 12345 --title "Updated Title" --body-file /tmp/body.md

バージョンは自動的にインクリメントされるため、手動で管理する必要はありません。大規模なページの更新には --body-file を使用してください。

コメント

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

attach を使用して、ローカルファイル（画像、PDF など）をページにアップロードします。アップロード後、ページ本文で <ac:image><ri:attachment ri:filename="screenshot.png" /></ac:image> を使用して画像を埋め込みます。サイズ指定のガイドラインについては、references/confluence-formatting.md を参照してください。

Confluence スペースをローカルの Markdown に同期

# 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

階層、画像、リンク付きタイトルを含む Confluence ページツリー全体を、ローカルの Markdown ファイルにダウンロードします。画像参照とファイル添付リンクの両方を、ローカルのアセットを指すように書き換えます。詳細とカスタマイズオプションについては、workflows/sync-confluence-space.md を参照してください。

スペースとナビゲーション

confluence.mjs spaces --max 20
confluence.mjs descendants 12345       # Get child pages

---

形式変換ユーティリティ

スクリプト：<skill-path>/scripts/confluence-format.mjs

このモジュールは、Markdown と Confluence ストレージ形式の双方向変換を提供します。confluence.mjs 内部で使用されますが、カスタム同期スクリプトから直接インポートすることもできます。

エクスポート関数

import { markdownToStorage, storageToMarkdown, htmlInlineToMarkdown } from '<skill-path>/scripts/confluence-format.mjs';

関数	方向	使用例
markdownToStorage(md)	Markdown → XHTML	Confluence への公開（confluence.mjs --body-file で自動使用）
storageToMarkdown(html)	XHTML → Markdown	Confluence ページをローカルの Markdown ファイルにダウンロード／同期
htmlInlineToMarkdown(html)	インライン HTML → Markdown	<strong>、<em>、<a>、<code> を含む可能性のあるスニペット（表のセル、リスト項目）の変換

storageToMarkdown が処理する内容

このコンバーターは、実際の Confluence ストレージ形式で使われる以下のパターンに対応しています。

• 構造化マクロ：コードブロック（言語指定あり／なし）、パネル（info/tip/warning/note → GitHub アラート）、expand → <details><summary> の折りたたみ可能なセクション、jira 参照、view-file → 添付ファイルへのリンク、toc/children（除去）
• 未知のマクロ：認識されない ac:structured-macro タイプでも本文コンテンツを保持します（暗黙に破棄されることはありません）。
• テーブル：<colgroup>、<tbody>、<thead> のラッパーを除去し、<table>、<tr>、<th>、<td> の属性を処理します。
• タスクリスト：<ac:task-id> を含む <ac:task-list> を Markdown のチェックボックスに変換します。
• 画像：URL と添付画像を ![alt](url) に変換し、代替テキストがない場合はファイル名を使用します。ファイル名に含まれる括弧とスペースは URL エンコードされます。
• コードブロック：プレースホルダー方式で HTML タグの除去から保護されるため、フェンス付きブロック内の Array<string> のような一般的な型も保持されます。
• 展開／折りたたみ可能な本文：expand マクロ内のコンテンツをすべてサポートします。コードブロック、画像、テーブル、パネル、タスクリスト、入れ子になったマクロが正しく変換されます。
• エンティティ：HTML エンティティを完全にデコードします（’、“、→、 、数値形式の {）。
• ブロック間の区切り：見出し、画像、リスト、<hr>、テーブル、コードブロックの前後に \n\n を挿入します。
• 属性への対応：すべての HTML タグ正規表現がオプション属性を受け入れます（Confluence の local-id、data-layout、breakoutWidth などに対応）。
• 太字／斜体の修正：マーカー内の末尾の空白を修正します（**text ** → **text**）。
• 余分な山括弧：Markdown レンダラーの誤認を防ぐため、コードブロック外ではエスケープします。

Confluence スペースの同期

ほとんどの用途では、組み込みの同期スクリプトを直接使用してください。

node <skill-path>/scripts/sync-confluence-space.mjs --root <pageId> --output ./docs

カスタムの同期スクリプトを使用する場合は、storageToMarkdown をインポートし、次のパターンに従ってください。

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}`;

本番環境での使用で判明した主な注意点：

• v2 API の _links.webui は相対パスです（例：/spaces/BTH/pages/123/Title）。完全な URL を作るには _links.base（例：https://company.atlassian.net/wiki）と結合してください。env.domain と _links.webui を直接使用してはいけません（/wiki プレフィックスが抜けます）。
• スペースや括弧を含む添付ファイル名は、Markdown のリンク内で URL エンコードする必要があります：![alt](Screenshot%202025-11-05%20at%2016.50.02.png)。
• 階層構造を同期する場合は、getChildrenTree()（再帰的な子要素 API）を使ってツリーを構築し、ノードごとに形式を決めてください。子を持つページは directory/index.md に、末端のページはフラットな PageName.md にします。
• 添付ファイルは共有の assets/imgs/ および assets/pdfs/ ディレクトリに保存してください。深さに応じた相対パスを使用します（深さ 1 では ../assets/imgs/、深さ 2 では ../../assets/imgs/ など）。
• 同期スクリプトでは、画像参照（![alt](filename)）とファイル添付リンク（[filename](filename)）の両方をローカルパスに書き換える必要があります。Confluence の view-file マクロは画像参照ではなく通常のリンクを生成します。
• Confluence はほとんどの HTML タグに属性（local-id、breakoutWidth、data-layout）を追加します。タグに一致させる正規表現では、オプション属性に対応するため [^>]* を使用してください。
• expand マクロの本文にはあらゆるコンテンツ（コードブロック、画像、テーブルなど）が含まれる可能性があります。内部 HTML コンバーターは、メインコンバーターと同じ種類の要素を処理する必要があります。

テストの実行

node <skill-path>/scripts/test-format.mjs

前方変換、逆変換、往復変換での保持、ブロック要素の間隔、コードブロックの保護、画像 URL のエンコード、エンティティのデコード、入れ子になったコンテンツを含む expand マクロ、view-file マクロ、未知のマクロの包括的な処理、HTML タグの属性への対応を網羅する 100 件以上のテストがあります。

ワークフロー

複数のターンにわたるユーザーとのやり取りが必要な複雑な複数ステップの操作では、対応するワークフローファイルを読み、記載された手順に従ってください。単純な一度限りのコマンドでは、上記の操作セクションを直接使用してください。

ワークフロー	使用する場面	ファイル
会議メモからタスクを作成	ユーザーが会議メモを提示し、アクションアイテムから Jira タスクを作成したい場合	workflows/capture-tasks-from-meeting-notes.md
ステータスレポートを作成	ユーザーがプロジェクトのステータスレポート、スプリントの概要、または週次更新を求めている場合	workflows/generate-status-report.md
社内ナレッジを検索	ユーザーが Confluence ページと Jira 課題を横断して情報を探したい場合	workflows/search-company-knowledge.md
仕様からバックログを作成	ユーザーが Confluence の仕様書を Epic と子チケットに分割したい場合	workflows/spec-to-backlog.md
課題をトリアージ	ユーザーがバグを報告し、登録前に重複チェックをしたい場合	workflows/triage-issue.md
Confluence ドキュメントを作成	ユーザーがマクロ、画像、構造化された書式を使用した、プロフェッショナルな Confluence ページを求めている場合	workflows/create-confluence-document.md
BMAD ドキュメントを同期	ユーザーがローカルの BMAD ドキュメント（Epic、技術仕様書、PRD、アーキテクチャ）を Jira または Confluence と同期したい場合、またはドキュメントをチケット／ページにリンクしたい場合	workflows/sync-bmad-documents.md
Confluence スペースを同期	ユーザーが階層、画像、リンク付きタイトルを保持したまま、Confluence スペース全体をローカルの Markdown ファイルにダウンロードしたい場合	workflows/sync-confluence-space.md

---

エラー処理

エラー	考えられる原因	解決方法
401 Unauthorized	API トークンが無効、または期限切れ	Atlassian のセキュリティ設定で再生成してください
403 Forbidden	権限が不足している	ユーザーのアカウントに対するプロジェクト／スペースの権限を確認してください
404 Not Found	課題キー、ページ ID、またはドメインが間違っている	リソースが存在すること、および ATLASSIAN_DOMAIN が正しいことを確認してください
429 Too Many Requests	レート制限に達している	少し待ってから再試行してください。バッチサイズを小さくしてください
環境変数が不足	設定されていない	node <skill-path>/scripts/setup.mjs を実行してください

---

リファレンスドキュメント

必要に応じて読み込んでください。最初にすべて読む必要はありません。

リファレンス	参照する場面
references/jira-api.md	Jira API のエンドポイントやリクエスト形式の詳細が必要な場合
references/confluence-api.md	Confluence API のエンドポイントやストレージ形式の詳細が必要な場合
references/confluence-formatting.md	マクロ、レイアウト、画像、ドキュメントテンプレートを使ってプロフェッショナルなページを作成する場合
references/query-languages.md	JQL または CQL クエリを作成する場合
references/jql-patterns.md	レポート、検索、フィルターでよく使われる JQL パターンが必要な場合
references/action-item-patterns.md	会議メモからアクションアイテムを抽出する場合
references/report-templates.md	ステータスレポートを作成する場合
references/bug-report-templates.md	適切に構成されたバグレポートを作成する場合
references/search-patterns.md	複数のソースを対象とした検索戦略が必要な場合
references/epic-templates.md	Epic の説明を作成する場合
references/ticket-writing-guide.md	明確なチケットの要約と説明を作成する場合
references/breakdown-examples.md	仕様をストーリーやタスクに分割する場合
references/sync-mapping-guide.md	初回のドキュメント同期前、フィールドのマッピングに失敗した場合、またはカスタムフィールドのマッピングを設定する場合