atlassian-rest-ops

atlassian-rest-ops

概要

このスキルを使うと、エージェントは curl で REST API を直接呼び出すことで、Confluence Cloud（v2）または Jira Cloud（v3）のあらゆる操作を実行できます。SDK も pip の依存関係も必要ありません。REST API は、Confluence ページの作成などの書き込み操作も含む、完全な API サーフェスです。エージェントは呼び出し元が注入した認証情報を使用し、同梱の OpenAPI 仕様から エンドポイントインデックスと $ref リゾルバーを使ってエンドポイントを検索し、curl を組み立てて JSON を解析します。Confluence と Jira では、ベース URL、ページネーション、エラー、リッチテキストなど、いくつかの点で異なるため、このスキルでは汎用的な形式を一つ使うのではなく、API ごとのパターンを用意しています。

有効化するタイミング

• ✅ Confluence Cloud v2 の操作（ページ、スペース、添付ファイルなどの作成、取得、更新、検索）を実行するとき。
• ✅ Jira Cloud v3 の操作（課題、コメントなどの作成、検索、トランジション）を実行するとき。
• ✅ Atlassian REST API に対してプログラムで書き込みや操作を行う必要があるとき（例：Confluence ページの作成）。

次の場合は有効化しないでください：

• 対象が Atlassian Server／Data Center の場合（このスキルは Cloud と API トークン専用です）。
• 認証情報の設定だけが必要な場合 — 認証情報は呼び出し元から提供されます。このスキルは認証情報をプロビジョニングしたり解決したりしません（このスキルが利用する契約については references/credentials.md を参照してください）。

ワークフロー

ステップ 1 — 注入された認証情報を受け取る

呼び出し元はすでにアカウントを解決し、この操作に必要な情報を注入しています。その情報を使用し、自分でレコードを探さないでください。コンテキストから次の情報を受け取ります。

• base_url と email（およびアカウントが使用する ケイパビリティ）— ファイルから読み取るのではなく、コンテキスト値として受け取ります。
• トークン。コンテキストに記載された変数名に対し、順序付きの読み込みルールを適用します。 その変数名を次のように解決します。そのファイルが存在し、変数が定義されている場合はプロジェクトレベルの .env の値を使用し、それ以外の場合はその名前の 環境変数を使用します。プロジェクトの .env が先に確認されます（これにより、プロジェクトの .env がグローバル環境変数を上書きできます）。トークンの値はコンテキストの説明文には含まれず、変数名のみが含まれます。curl は環境から値を読み取ります。プロジェクトのルートはコンテキストから提供されるため、.env を探すためのスコープ解決やディレクトリ探索は行わないでください。また、対象はプロジェクトの .env であり、.envrc ではありません。

これらを、サンプルスクリプトで固定されている変数 ATLASSIAN_EMAIL／ATLASSIAN_BASE_URL／ATLASSIAN_API_TOKEN に橋渡しします（以前と同じ橋渡しです。入力元のみがコンテキストになりました）。契約全体と橋渡しの方法については、references/credentials.md を参照してください。

ステップ 2 — エンドポイントを見つける

assets/endpoint-index.md を検索し、必要な操作を見つけます（操作ごとに 1 行で、形式は METHOD path — summary (operationId) です）。完全な仕様をコンテキストに読み込まないでください。数 MB あるためです。

ステップ 3 — 呼び出しの形式を解決する

リゾルバーを実行します：python3 scripts/endpoint.py <confluence|jira> <operationId>。バンドルされた OpenAPI 仕様から対象の操作 1 件を参照解決し、メソッド、パス、パラメーター、リクエスト／レスポンスのスキーマ、curl のひな形を出力します（scripts/endpoint.py とその検証機能は拡張時に追加されます。「段階的な情報開示」を参照してください）。

ステップ 4 — curl を組み立てて実行する

references/patterns.md にある API ごとのパターンを適用します。

• 認証（両方）：curl -u "$email:$<token_env>"（HTTP Basic）。
• ベース URL： Confluence → <base_url>/wiki/api/v2/<path>、Jira → <base_url>/<path>（パスにはすでに /rest/api/3/… が含まれています）。
• リッチテキストの本文（間違えやすい部分）— references/rich-text.md を参照してください。Jira は ADF を生の JSON オブジェクトとして使用します。Confluence は {representation, value} を使用し、atlas_doc_format は ADF JSON を文字列化したもの、storage は XHTML 文字列を意味します。入力がMarkdown（書式付きコメントなど）の場合は、生の Markdown を送信するのではなく、python3 scripts/md_to_adf.py < body.md で ADF に変換してください（生の Markdown を送信すると、##／**／| が文字どおり表示されます）。
• application/json を送信／受け入れます。

ステップ 5 — レスポンスを処理する

• ページネーション： Confluence → カーソルを使い、_links.next に従います。Jira → startAt/maxResults（および total/isLast）、または新しいエンドポイントでは nextPageToken を使います。references/patterns.md を参照してください。
• エラー： Jira は ErrorCollection {errorMessages, errors, status} を返し、Confluence はインラインのエラー JSON を返します。HTTP 429（Jira）の場合は、バックオフして再試行します。

ルール

厳守するルール（決して違反しないこと）：

• SDK も pip も使いません。 API 呼び出しには curl を使います。唯一のヘルパーは scripts/endpoint.py です（python3 の 標準ライブラリのみ）。
• トークンの値を読み取ったり表示したりしないでください。 curl -u 引数内では $<token_env> としてのみ参照します。サブプロセスが環境変数から読み取ります。トークンは .env（gitignore 対象）にのみ保存します。
• 構築前に解決します。 リクエスト本文やパラメーターは、$ref を解決したスキーマ（ステップ 3）または検証済みのリッチテキスト形式に基づいて構築します。推測や記憶に頼ったフィールドセットは使いません。
• API ごとに適用し、汎用化しません。 Confluence と Jira のパターン（ベース URL、ページネーション、リッチテキスト、エラー）を正しく適用します。それぞれ異なります。
• リッチテキスト： Jira の ADF は生のオブジェクトです。Confluence の atlas_doc_format は value 内の文字列化された ADF です。混同しないでください。
• このスキルは認証情報を書き込みません。 認証情報は呼び出し元から提供されます。このスキルが認証情報を発行したり解決したりすることはありません。

推奨事項（上書き可能）：

• 旧式の /search（startAt）より、新しい Jira の課題検索 GET /rest/api/3/search/jql（nextPageToken）を優先してください。
• レスポンスを小さく保つため、必要なフィールドのみをリクエストしてください（Jira では fields=、Confluence では body-format=）。

注意点

• リッチテキスト形式の不一致。 Confluence の atlas_doc_format に生の ADF オブジェクトを送信する（文字列化したものではなく）こと、または Jira に文字列化されたデータを送信する（生のオブジェクトではなく）ことが、最もよくある失敗です。Confluence の value は常に文字列です。
• ベース URL の違い。 Confluence のパスは …/wiki/api/v2 を基準にします。Jira のパスにはすでに /rest/api/3 が含まれています。/wiki を重複して付けたり、省略したりしないでください。
• $ref の連鎖。 リクエスト本文が仕様内に直接記述されていることはほとんどありません。通常はスキーマを参照し、そのスキーマがさらに別のスキーマを参照する場合もあります。リゾルバー（ステップ 3）を使ってください。仕様を単純に grep しても、完全な構造はわかりません。
• 旧式と新式の Jira 検索。 GET /rest/api/3/search は GET /rest/api/3/search/jql によって非推奨になります。ページネーションも異なります（startAt と nextPageToken）。
• レート制限。 Jira は Retry-After を伴う HTTP 429 を返します。その値に従ってください。Confluence はリクエスト本文が大きすぎる場合に 413 を返すことがあります。
• Confluence の削除は 2 段階です（実環境で検証済み。ページ、ブログ投稿、その他のコンテンツに適用されます）。DELETE /pages/{id}（または /blogposts/{id}）で行われるのはごみ箱への移動だけです（204 が返されますが、GET では status: trashed として引き続き取得できます）。完全に削除するには、DELETE /<type>/{id}?purge=true を呼び出します。これはごみ箱に移動した後にのみ機能します（ごみ箱への移動なしでの完全削除は何も行いません）。通常の削除だけでは完全に削除されません。
• Jira の /search/jql は制約のない JQL を拒否します（実環境で検証済み）。並べ替えのみ、または空の JQL を指定すると、400 ErrorCollection（「Unbounded JQL queries are not allowed here」）が返されます。必ず検索条件を含めてください（例：project = X、created >= -30d）。

アンチパターン

• リクエスト本文を推測する。 「Jira の課題がどのような形式か」という記憶を頼りにリクエスト本文を手書きしないでください。スキーマを解決してください。必須フィールドはプロジェクトや画面によって異なります。
• トークンを表示する。 echo $TOKEN を実行したり、表示するコマンドにトークンを貼り付けたり、その値をファイルに書き込んだりしないでください。curl 内で環境変数を参照する場合に限ります。
• 仕様全体を読み込む。 数 MB の OpenAPI JSON を cat したり読み込んだりしてコンテキストに含めないでください。インデックスを調べ、1 つの操作を解決してください。
• すべてに同じ方法を適用する。 Jira のページネーション、エラー処理、ADF を Confluence に適用したり、その逆を行ったりしないでください。
• SDK に頼る。 atlassian-python-api や pip install に手を伸ばさないでください。curl とリゾルバーで、すべてのエンドポイントに対応できます。

出力

このスキルはAPI に副作用（要求された Confluence／Jira 操作）をもたらし、解析済みの JSON レスポンスを呼び出し元のエージェントに返します。このスキル自体はファイルを書き込みません（呼び出し元から注入された認証情報を使用するだけです）。書き込み操作では、作成または更新したリソース（id、key、URL）を報告し、読み取り操作では、必要に応じてページネーションを行い、結果セットを返します。抽象的な利用者は、操作の実行を必要とする呼び出し元のエージェント（またはサブエージェント）です。シークレットが出力に含まれることはありません。

関連情報

• references/credentials.md — このスキルが使用する認証情報の契約（呼び出し元から注入されるフィールド、順序付きのトークン読み込みルール、固定変数へのブリッジ）。
• REST への直接アクセスとバンドルされた OpenAPI 仕様のパターンは、ほかの API プロバイダーにも一般化できます。

段階的な情報開示

詳細なコンテンツはサブフォルダーに格納されており、必要な場合にのみ読み込まれます。

• references/patterns.md — API ごとのパターン：認証、ベース URL、ページネーション（Confluence のカーソル方式と Jira のオフセット／トークン方式）、レスポンスのエンベロープ、エラー、レート制限、expand。ステップ 4～5 で読み込みます。
• references/rich-text.md — ADF（Jira、raw object）と Confluence の本文表現（storage／atlas_doc_format、文字列としての値）の実例と、API 間での注意点。リクエスト本文を作成する際に読み込みます。
• references/credentials.md — このスキルが使用する認証情報の契約：呼び出し元から注入されるフィールド、順序付きのトークン読み込みルール、固定変数へのブリッジ、シークレットの適切な取り扱い。ステップ 1 で読み込みます。
• references/sources.md — 情報源（Atlassian 公式ドキュメントとバンドルされた仕様のバージョン）。

拡張時（フェーズ 2.C）に追加され、上記で参照されるもの：

• assets/confluence-v2.json、assets/jira-v3.json — バンドルされた OpenAPI 仕様（信頼できる情報源。必要な情報を照会し、全体を読み込むことはありません）。
• assets/endpoint-index.md — 操作ごとに 1 行の、検出用インデックス（ステップ 2）。
• scripts/endpoint.py + scripts/endpoint.py.validation.md — python3 用の $ref リゾルバー（ステップ 3）。
• scripts/<op>.sh + .validation.md — 検証済みの curl の例 4 件（Confluence ページの作成、Confluence の一覧取得、Jira 課題の作成、Jira の検索）。
• scripts/md_to_adf.py + .validation.md — 標準ライブラリのみを使う Markdown -> ADF コンバーター。Markdown のコメント／説明文をパイプで渡すと、ネイティブ ADF として投稿できます（見出し、太字、コード、リンク、リスト、GFM テーブルが、##／| の生テキストとして表示されずにレンダリングされます）：python3 scripts/md_to_adf.py < comment.md -> Jira の {"body": ...} 用 ADF オブジェクト。

単独での使用（任意、必須ではありません）

これはエージェントフローの外で人が手動でスキルを実行する場合に便利な方法であり、スキルの依存関係ではありません。スキルの規定上の契約は呼び出し元からの注入（ステップ 1）です。この付録は手動実行者向けの橋渡しにすぎません。

手動で実行するには、.service-accounts.yaml のレコードとその .env トークンを使って、3 つの固定変数を自分で設定してからスクリプトを実行します。レコードの例：

accounts:
  - name: atlassian-work
    provider: atlassian
    base_url: https://workco.atlassian.net
    email: [email protected]
    token_env: ATLASSIAN_WORK_API_TOKEN     # the var holding the token value; value lives in .env (gitignored)

set -a; source .env; set +a                 # loads $ATLASSIAN_WORK_API_TOKEN, never prints it
export ATLASSIAN_EMAIL="[email protected]"
export ATLASSIAN_BASE_URL="https://workco.atlassian.net"
export ATLASSIAN_API_TOKEN="$ATLASSIAN_WORK_API_TOKEN"
bash scripts/create-confluence-page.sh <space-id> "<title>"

API トークンは id.atlassian.com → Security → "Create API token" から取得してください。値は名前でのみ参照され、表示されることはありません。

本文の上限

• description は 1,024 文字以下（agentskills.io の上限）。
• 本文は約 500 行／5,000 トークン以下 — 毎ターンのコンテキストに保持されます。API ごとの詳細は references/ にあります。
• assets/*.json は大きいため、ディスク上で照会し、コンテキストには読み込みません。