Claude CodeのAtlassian Forgeプラグインで雛形作成から本番デバッグまで

forge-skillsプラグインは、Atlassian Forge(JiraやConfluence上で動くアプリを、Atlassianのプラットフォーム上に直接デプロイする仕組み)の開発をClaude Codeに任せるためのプラグインです。7つのskillsと2つのMCPサーバーが1つにまとまっていて、雛形作成、デプロイ前レビュー、本番障害の調査を、場面ごとに別のskillが受け持ちます。

提供元はAtlassian Labsで、マーケットプレイスの掲載ページには383件のインストールと表示されています。リポジトリのライセンスはApache 2.0、プラグインのバージョンは0.1.0です。ここでは導入から、場面別の使い分け、自動実行を許す範囲の決め方までを順に説明します。

このプラグインに入っているもの

Claude Codeのプラグインは、skillsやMCPサーバーを1つの配布単位にまとめる仕組みです。forge-skillsはその典型で、中身は次の3層に分かれます。

2つのMCPサーバーの接続先は、リポジトリの .mcp.json に書かれています。

• forge: HTTP接続で https://mcp.atlassian.com/v1/forge/mcp
• ads-mcp: https://mcp.atlassian.com/v1/ads/public/mcp

ADS側には type の指定がなく、URLだけが書かれています。

同じ構成を持つ他社のプラグインは、プラグイン同梱のMCPサーバーの仕組みで届きます。自分で claude mcp add を打つ必要はありません。

導入前に揃えるもの

リポジトリのPrerequisitesには3つ挙がっています。

Node.jsのバージョンは node -v で見られます。Forge CLIが入っていない環境では、トラブルシューティングの記載どおり npm install -g @forge/cli で入れます。forge: command not found が出たときの対処としても同じ行が書かれています。

インストールして動作を確かめる

Claude Code向けのインストールは1行です。

/plugin install forge-skills@atlassian-forge-skills

@atlassian-forge-skills の部分は、リポジトリの .claude-plugin/marketplace.json に書かれたマーケットプレイス名です。まだそのマーケットプレイスが登録されていない環境では、先に /plugin marketplace add atlassian/forge-skills で追加すると解決できます(Claude Codeのマーケットプレイス追加の一般的な書き方です)。

READMEは導入後に4つの確認を勧めています。それぞれ「何が返れば成功か」まで書かれているので、そのまま使えます。

動かないときの切り分けも、READMEの3項目で足ります。skillsが使われないなら、skills/ に上の7つが入っているかを確かめ、ホストを再起動してプラグインを読み直させます。MCPツールが出ないなら、Forge MCPの設定が入ったかと node -v を確かめます。認証で落ちるなら forge login をやり直し、正しい開発者スペースが選ばれているかを見ます。

forge loginは自分のターミナルで打つ

認証はプラグインではなくForge CLIが担います。forge login を実行すると、AtlassianのメールアドレスとAPIトークンが求められ、forge whoami でログイン状態を確かめられます。READMEは、認証情報は自分のターミナルにだけ入力し、チャットにトークンを貼らないよう明記しています。

この扱いはskill側にも反映されています。forge-app-builder は「認証情報をチャットで要求も受領もしない」を不変条件の1つにしていて、forge-debugger も、対話ターミナルが必要な forge login と forge tunnel だけは自分で実行せず、ユーザーに打ってもらう例外として扱います。

APIトークンは id.atlassian.com/manage/api-tokens で作り直せます。ログインが通っているのに失敗するときは、トークンの期限切れと並べて、開発者スペースの選択違いも確かめてください。READMEも、再ログインと正しい開発者スペースの確認を並べて挙げています。

場面別に、どのskillが動くか

7つのskillは、SKILL.md の説明文にある「使う場面」と「使わない場面」で呼び分けられます。依頼文のキーワードに反応して自動で選ばれるので、名前を指定する必要はありません。

残りの forge-cost-optimizer は呼び出し回数、ストレージ、ログ、メモリの消費を減らす専門、forge-security-review はソースを読んで認可、インジェクション、テナント分離、シークレットの扱いを調べるホワイトボックス監査の専門です。レビューのskillは、深い調査が必要になった時点でこの2つに引き継ぎます。

forge-connector は、外部データをRovo SearchやRovo Chatに取り込む graph:connector アプリを作るときの専門です。

雛形を作る:forge-app-builderの動き

雛形作成を頼むときは、作りたい画面と連携先をそのまま書きます。READMEの例文には、次のようなものがあります。

• 外部APIのサポートチケットを表示するJira課題パネルを作る
• 棒・折れ線・円グラフを切り替えられるConfluenceマクロを作る
• 優先度別に未完了課題を集計するJiraダッシュボードガジェットを足す
• Confluenceアプリが、Jiraのデータも読むのに必要なスコープを調べる

forge-app-builder の不変条件は、Forgeの現行仕様に基づいて動くためのものです。構文、モジュール、スコープ、CLIフラグを決める前に、現行の公式ガイドを引くこと。新規アプリは必ず forge create で登録し、手作りの足場で代用しないこと。マニフェストを変えたら公式リファレンスと forge lint で検証すること。最小権限を守ることも挙がっています。

最初に引く情報源は、利用できる場合Forge MCPです。ツール名を固定で覚えず、その時点で使える機能を用途で探して、最も範囲の狭いものを呼ぶ方針です。MCPが失敗したときや、特定の仕様を厳密に確認したいときだけ、Atlassianの公式ドキュメントに当たります。

作業は「小さく変えて、そのたびに検証する」形で進みます。テスト、型チェック、フロントエンドのビルド、forge lint のうち、その変更に関係の深いものを選びます。リント通過だけで「動く」とは扱わず、より強いローカル検証が可能ならそちらを使う、という書き方です。止まる位置もはっきりしていて、ローカル検証が済んだところで終わり、デプロイは依頼があったときだけ進みます。

デプロイ前に見る:forge-app-reviewの出力

forge-app-review は、リリース前の「広く浅い」点検役です。冒頭の規則は「まず監査し、ユーザーが明示しない限りアプリのファイルを変更しない」で、コードを読んでから指摘し、できる限り行番号付きの根拠を添えます。

見る観点は、マニフェストが参照するハンドラーやリソースパスの欠落、フロントエンドが呼ぶリゾルバー名と resolver.define() の名前の不一致、実際のAPI呼び出しに対するスコープや外部通信許可の不足、forge lint やビルドで落ちそうな構文です。軽い兆候として、権限が広すぎるスコープ、認可チェックの見えないリゾルバーでの api.asApp()、外部通信先がマニフェストに無いfetch、リクエスト全体のログ出力なども拾います。

出力は決まった形で、サマリー、指摘の表、問題のなかった領域、次の一手の順です。指摘の表には、深刻度、出どころ、引用付きの位置、説明、公式ドキュメントへの参照、修正案の列が付きます。

# Forge App Review Results
- Readiness: Ready | Needs changes | Blocked
- Specialist handoffs: none | security | cost | debugger

表の末尾に「専門skillへの引き継ぎ」欄があるのがこのskillの特徴です。深いセキュリティ監査は forge-security-review へ、コスト最適化は forge-cost-optimizer へ、すでに起きている不具合は forge-debugger へ渡す、という切り分けが説明文に書かれています。広いレビューで専門領域の問題を見つけても、重複して深追いはしません。

本番で起きていることを調べる:forge-debuggerの順序

forge-debugger は、原因が見つかった時点で止まる設計です。まず、エラーがデプロイ時、実行時、表示されない問題のどれかを分類します。メッセージから明らかなら質問は省きます。症状ごとの入口は、次のように表で定められています。

調査の順番は「安いものから」です。forge --version と npm show @forge/cli version で版を比べ、古ければ更新し、次に forge lint を回します。マニフェスト関連のエラーでは、ソースを読むより先に forge lint の出力を見る、とも書かれています。ログを読むのは、その後です。

本番だけで起きる不具合には専用の手順があります。

# 影響を受けているサイトを聞いたうえで、本番ログを確認する
forge logs -e production --site <顧客のサイト> --limit 100

本番ログはイベントから最大2分ほど遅れて出ることがあります。権限が原因に見えるときは、新しくインストールし直したあとにスコープが更新されたかを確かめます。本番のインストールでは、--upgrade の明示が必要だからです。

複数の障害が重なっていれば、デプロイ時のエラーを先に直し、デプロイしてから実行時のログを見ます。1つ目を直して「完了」と宣言しないことも、原則に書かれています。

自動実行の範囲を、Claude Code側で決めておく

ここまでの動きには、読む側が整理しておきたい食い違いが1つあります。forge-debugger の冒頭には「診断と修正のコマンドは許可を求めずに実行する」という実行方針があり、「こう実行してください」と案内するのではなく、自分で実行して結果を報告する書き方です。一方、forge-app-builder は、デプロイ、インストール、アップグレード、本番変数の設定を、明示的な許可と対象の確認なしには行いません。

プラグインがskillの中で自制していても、権限の最終的な線引きはClaude Code側に置くのが堅実です。デプロイとインストールだけは毎回確認を挟む設定を、プロジェクトに入れておく例を示します(.claude/settings.json の例です)。

{
  "permissions": {
    "ask": [
      "Bash(forge deploy:*)",
      "Bash(forge install:*)"
    ]
  }
}

forge lint や forge logs のような読み取りに近いコマンドは、確認なしで回せます。forge deploy と forge install が確認付きになるので、バグ修正の流れが自動で本番まで走ることを防げます。forge login と forge tunnel は対話ターミナルが必要なので、どのみち自分で打つことになります。

CLAUDE.mdには、使う環境を短く書き足しておくと迷いが減ります。

# Forgeアプリの作業ルール
- デプロイ先の既定は development 環境。production は明示指示があるときだけ
- 本番の調査は forge logs -e production --site で、変更を加える前に必ずログを読む
- マニフェストを変えたら forge lint を通してから報告する

この3行は、プラグインが元から持つ原則をプロジェクトの言葉に置き直しただけのものです。skillの再実装ではなく、確認の線をこちらに寄せる補助として機能します。

導入前に押さえる境界

• 接続先は外部:2つのMCPサーバーは mcp.atlassian.com に接続します。Atlassianが運営するエンドポイントなので、社内の機密仕様を質問文に含めるかは組織の方針に合わせて判断します
• ADS MCPはCustom UI専用:UI Kitで作るアプリには出番がありません。READMEが「Custom UI only」と明記しています
• 他のホストでも使えるが、手順が違う:CursorやGemini CLI、GitHub Copilot CLI、OpenAI Codex、Kiro向けにも導入手順が用意されています。Rovo Devだけはプラグイン導入に未対応で、skillsを npx skills add atlassian/forge-skills で入れ、MCPの設定を手で追加します
• バージョンは0.1.0:初期版なので、SKILL.mdの記述やコマンド例は更新されます。迷ったらリポジトリのREADMEが基準です

本番の障害をClaude Codeに調べさせる使い方は、監視基盤のデータを読むgroundcoverプラグインと目的が近く、こちらはForgeのログとCLIに閉じた調査になります。デプロイ前に差分をレビューしたいだけなら、code-reviewプラグインのほうが汎用的です。Forge固有のマニフェストやスコープまで見るかどうかが、選ぶ分かれ目になります。

まとめ

forge-skillsは、Forgeの雛形作成、レビュー、デバッグを分担する7つのskillと、公式ドキュメントを引く2つのMCPサーバーの束です。導入は /plugin install forge-skills@atlassian-forge-skills の1行ですが、運用で効くのは、forge login を自分で打つこと、forge deploy と forge install に確認を挟むこと、本番調査はサイトを指定して forge logs から入ること、の3点です。