claude-code-actionのpromptにリポジトリ内スキルを渡してPRごとに実行する

claude-code-actionのpromptには、文章の代わりに/skill-nameを渡せます。リポジトリの.claude/skills/に置いたスキルを呼ぶなら、anthropics/claude-code-actionのステップより前にactions/checkoutを置きます。順序が逆だと、スキルのファイルがランナーに存在しません。

この記事では、PRごとにスキルを走らせるワークフローを例に、書き方と権限の渡し方、プラグイン経由で呼ぶ場合との違いをまとめます。入力パラメータの一覧はGitHub Actionsのパラメータとclaude_argsの渡し方が扱っているので、ここではpromptにスキルを渡す手順に絞ります。

promptにスキル名を渡すと何が起きるか

claude-code-actionは、promptの有無で動き方が変わります。promptが無ければ、@claudeのメンションを待つ対話モードです。promptがあれば、メンションを待たずに走る自動化モードになります。スキルを呼ぶのは後者です。

自動化モードでは、結果はデフォルトでワークフローの実行ログに出ます。PRにコメントを残すかどうかは、プロンプトやスキルの指示と、コメントを投稿できるツールがあるかで決まります。

スキルの置き場所で、渡し方が2通りに分かれます。

どちらもpromptにスラッシュ付きで渡す点は同じです。違いは、スキルのファイルをどうやってランナーに届けるかにあります。

checkoutを先に置く理由

GitHub Actionsのランナーは、ジョブごとに空の環境から始まります。自分のPCの.claude/skills/も、リポジトリの中身も、チェックアウトしなければ入っていません。actions/checkoutは、リポジトリのファイルをランナーに置くステップです。

リポジトリ内のスキルを呼ぶ順序は決まっています。actions/checkoutをanthropics/claude-code-actionより前に置き、そのうえでpromptに/skill-nameを渡します。

GitHub Actionsのドキュメントにある定時レポートの例は、checkoutを省いています。Claudeがコミットやissueを読むのにGitHub APIのツールを使うので、ローカルのコピーが要らないからです。「checkoutが要るかどうか」は、Claudeがファイルを読むのか、APIで済むのかで決まります。スキルのSKILL.mdはファイルなので、リポジトリ内のスキルを呼ぶなら必須です。

PRごとに走らせるワークフローの例

次は、PRが開かれたとき、更新されたとき、再オープンされたとき、レビュー準備完了になったときに、リポジトリ内のpr-checklistスキルを実行する例です。構成は公式のコードレビュー例に合わせています。

mkdir -p .claude/skills/pr-checklist

.claude/skills/pr-checklist/SKILL.mdは、たとえば次のように書きます。これは書き方を示す例で、公式のサンプルではありません。

---
name: pr-checklist
description: PRの変更がチームのチェックリストを満たしているか確認する
disable-model-invocation: true
---
 
$ARGUMENTS で指定されたPRの変更内容を読み、次を確認してください。
 
- 公開APIを変えた場合、docs/ の該当ページも更新されているか
- 新しい環境変数に、READMEの設定表への追記があるか
- テストを追加せずに分岐を増やしていないか
 
問題が無ければ「指摘なし」とだけ答えてください。

disable-model-invocation: trueは、Claudeが会話の流れで勝手にこのスキルを読み込むのを止める設定です。手動で/pr-checklistと呼ぶ用途に向きます。ワークフローから明示的に呼ぶなら、これを付けても動作に支障はありません。

ワークフロー側は次のとおりです。

name: PR Checklist
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  checklist:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "/pr-checklist ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

fetch-depth: 1は直近のコミットだけを取得する指定です。スキルのファイルを読むだけなら、コミット履歴まで取り込む必要はありません。

promptの中身は、スキル名とそのあとの引数です。スキルの本文にある$ARGUMENTSは、スキル名の後ろに書いた文字列に置き換わります。ここではリポジトリ名とPR番号が入ります。引数を受け取る書き方は、スキルのドキュメントの「Pass arguments to skills」にあります。

出力先は実行ログです。PRにコメントさせたいなら、スキルの本文でコメントの投稿を指示し、そのためのツールも許可します。

スキルの権限はallowed-toolsとclaude_argsで分かれる

自動化モードで悩みやすいのが、ツールの許可です。文章のプロンプトとスキルでは、ツールを許可する場所が違います。

• 文章のプロンプトを渡した場合、claude_argsの--allowedToolsか、settings入力のpermissions.allowで許可したツールだけが、シェルやGitHub APIの操作に使えます
• スキルを呼んだ場合、スキルのallowed-toolsフロントマターが許可するツールを使えます

つまり、スキルのフロントマターにallowed-toolsを書いておけば、promptを文章で書くよりclaude_argsが短くなります。たとえば次のようにします。

---
name: pr-checklist
description: PRの変更がチームのチェックリストを満たしているか確認する
allowed-tools: Read Grep
---

注意点が2つあります。

1つ目は、allowed-toolsの効く期間です。スキルのドキュメントによると、許可はスキルを呼んだターンの間だけ有効で、次のメッセージを送ると消えます。許可されていないツールが使えなくなるわけではなく、確認なしで使えるツールを増やす設定です。

2つ目は、MCPツールの例外です。公式のコードレビュー例は、スキル側のallowed-toolsに同じツール名があっても、claude_argsに--allowedTools "mcp__github_inline_comment__create_inline_comment"を残しています。インラインコメントを投稿するMCPサーバーは、claude_argsの--allowedToolsがそのツールを挙げたときだけ起動するためです。MCPツールをスキルから使うなら、claude_argsにも書いてください。

スキルのドキュメントは、プロジェクトのスキルのallowed-toolsが信頼確認なしで適用されること、スキル自身が広いツール権限を与えられることを注意しています。コミットされたスキルのallowed-toolsは、コードと同じようにレビュー対象になります。

プラグイン経由で呼ぶ場合の違い

スキルをプラグインにまとめて配っているなら、リポジトリに.claude/skills/を置く必要はありません。かわりに、次の2つの入力でプラグインを入れます。

plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
plugins: "code-review@claude-code-plugins"
prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

違いは3点です。

1. pluginsにはプラグイン名@マーケットプレイス名の形で書く。@の右は、リポジトリのURLではなく、マーケットプレイス自身のマニフェストに書かれた名前
2. promptは/plugin-name:skill-nameと、プラグイン名の名前空間を付ける
3. スキルを入れる作業が、checkoutではなくplugin_marketplacesの取得になる

plugin_marketplacesを使ったときにバイナリが配置されず失敗する報告については、plugin_marketplacesでバイナリが配置されない原因と対処で扱っています。

リポジトリ内のスキルは、プラグインのように名前空間が付きません。/pr-checklistのように短い名前で呼べるぶん、同名のスキルが複数の場所にあると、どれが動くかを確認する必要があります。スキルのドキュメントでは、エンタープライズ、個人、プロジェクトの3か所のうち2か所に同じ名前があれば、エンタープライズが個人に、個人がプロジェクトに優先すると説明されています。GitHub Actionsのランナーには個人のスキルが入っていないので、通常はプロジェクト側の1本だけが見えます。

動かないときの切り分け

動かない場合は、上から順に確認します。

フォークからのPRにも注意が要ります。公開リポジトリでは、フォークから出たPRで起動したワークフローにGitHubがシークレットを渡しません。公式のコードレビュー例も、同じリポジトリ内のブランチから出たPRでだけ動くと説明しています。

費用と実行回数の抑え方

PRごとに走らせると、synchronizeのたびにスキルが再実行されます。公式の費用の節では、次の手が挙がっています。

• claude_argsに--max-turnsを付けて、反復回数に上限を置く
• ワークフローにタイムアウトを設定する
• GitHubのconcurrency（並行実行の制御）で、並列に走る実行数を絞る

スキル本文に「何を見るか」を絞って書くことも、ターン数とトークンの節約になります。CLAUDE.mdも毎回読まれるので、短く保つ必要があります。

PRのたびに必ず走らせたいチェックと、人がメンションしたときだけ走らせたいチェックを分けたいなら、後者はpromptを省いた対話モードで運用する選択肢があります。

よくある質問

個人用スキルを~/.claude/skillsに置いたままCIで呼べますか

呼べません。ランナーには自分のPCのホームディレクトリがありません。CIで使うスキルは、リポジトリの.claude/skills/にコミットするか、プラグインにまとめてpluginsで入れます。

.claude/commandsのファイルもpromptで呼べますか

スキルのドキュメントによると、.claude/commands/deploy.mdと.claude/skills/deploy/SKILL.mdはどちらも/deployを作り、同じように動きます。既存のコマンドファイルがあるなら、チェックアウトさえ先に済ませれば同じ書き方で呼べます。新しく作るなら、補助ファイルを置けるスキルのディレクトリ形式が向きます。

まとめ

リポジトリ内のスキルをPRごとに走らせる要点は、actions/checkoutを先に置くことと、ツールの許可の置き場所を決めることの2つです。ファイルを読むだけのスキルならallowed-toolsで足ります。MCPツールで投稿させるならclaude_argsの--allowedToolsも要ります。社内の複数リポジトリで同じスキルを使うなら、プラグインにして/plugin-name:skill-nameで呼ぶほうが、スキルの更新を1か所で済ませられます。導入全体の流れはClaude Code GitHub Actions連携ガイドにあります。