CircleCI では、AI エージェント向けの公式スキル群を CircleCI-Public/skills として公開しました。これは Claude Code などのコーディングエージェントに CircleCI のベストプラクティスを持ち込むためのプラグインで、CircleCI環境のセットアップや.circleci/config.yml の診断・最適化・CIエラーの調査などをエージェントに指示させる際に利用します。

本記事では、この公式スキルのうち「CI設定の診断と最適化」について Claude Code
へインストールして診断と修正提案、そして PR にするまでを紹介します。

本記事は 2026 年 7 月時点のリポジトリ内容にもとづく速報です。収録スキルやインストール方法は今後変わる可能性があります。最新の状態は CircleCI-Public/skills を確認してください。

Claude Code に CircleCI 公式プラグインを導入する

プラグインのインストールはコーディングエージェント側で実装します。Claude Codeの場合、３つのコマンドを実行することになります。

まず/plugin marketplace add でカタログを登録してください。

❯ /plugin marketplace add CircleCI-Public/skills
  ⎿  Successfully added marketplace: circleci-public-skills

その次に/plugin install でプラグインを入れます。

❯ /plugin install circleci@circleci-public-skills
  ⎿  ✓ Installed circleci. Run /reload-plugins to apply.

最後に/reload-plugins で有効化してください。

❯ /reload-plugins
  ⎿  Reloaded: 2 plugins · 0 skills · 6 agents · 1 hook · 3 plugin MCP servers · 0 plugin LSP servers

インストールが完了したかどうかは、/plugin list で確認できます。

❯ /plugin list
  ⎿  Installed plugins:
       • circleci@circleci-public-skills (v1.0.0, project) ✔ enabled

/plugin list の出力で circleci@circleci-public-skills が enabled になっていれば、導入は完了です。

/reload-plugins を実行しないと、インストール直後はスキルが有効化されず /circleci:config を呼び出せません。インストール後は必ず再読み込みしてください。

`.circleci/config.yml` を診断させる

有効化できたら、/circleci:config に診断を依頼してみましょう。今回は「レビューと修正提案を」とだけ指示しました。

config スキルは、依頼に対して決まった 4 部構成で回答します。1 つ目が Baseline bottleneck summary（現状のボトルネックの要約）、2 つ目が Proposed changes（根拠つきの変更提案）、3 つ目が Expected impact（想定される効果）、4 つ目が Validation & rollback（検証手順と切り戻し方法）です。

今回の対象は、8 個のテストファイルからなるテストスイートです。/circleci:config の出力（抜粋）は次のような内容でした。

❯ /circleci:config レビューと修正提案を

  Searched for 3 patterns, read 6 files, ran 2 shell commands

Baseline bottleneck summary

8 test files, dominated by one artificial 8.8s file (heavy.test.ts, a sleep 8s).
All other 7 files run in well under 1s.

┌───────────────────┬──────────┬─────────────┬─────────────────────────────────────┐
│        Run        │ duration │ parallelism │ credits (medium, ≈10/min/container) │
├───────────────────┼──────────┼─────────────┼─────────────────────────────────────┤
│ No split (serial) │ 14.8s    │ 1           │ ≈2.5                                │
├───────────────────┼──────────┼─────────────┼─────────────────────────────────────┤
│ Split, timings    │ 14.3s    │ 4           │ ≈9.6                                │
└───────────────────┴──────────┴─────────────┴─────────────────────────────────────┘

This is the core finding: parallelism=4 buys essentially zero wall-clock
improvement (14.8s → 14.3s) while spending ~4x the credits. Root cause is
structural — file-level splitting can never beat the runtime of the single
slowest file, and here one file (heavy.test.ts, 8.8s) is ~69% of total suite time.

Proposed changes
1. Drop parallelism from 4 to 2 in .circleci/config.yml.

Expected impact
- Wall-clock: roughly unchanged (~14–15s), since the heavy file is still the ceiling.
- Credits: roughly half of the current ~9.6/run (≈4.8).

Validation & rollback
- Validate by triggering the pipeline and comparing against the ≈14.3s baseline.
- Rollback: revert parallelism: 2 → parallelism: 4; one-line change.

英語で生成されていますが、内容を要約すると「過剰なパラレル実行を発見し、並列数の削減を提案する」出力となっています。

テストをファイル単位で分割する方式では、コンテナをいくら増やしても、最も遅い 1 ファイル（heavy.test.ts、約 8.8 秒＝スイート全体の約 69%）の実行時間より速くはなりません。並列数を 4 にしても実行時間が 14.8 秒から 14.3 秒へほとんど変わらないという結果が出たため、並列数を削減する提案を出すことを判断した様子です。これは、config スキルのガードレール「実証されたボトルネックだけを並列化する（Parallelize only proven bottlenecks）」に沿ったものです。並列数という設定値ではなく、単一ファイルという構造がボトルネックである以上、コンテナを増やしても効果は頭打ちになる、という判断です。

config スキルは入力として「最も遅いジョブ」「リトライ頻度」などのベースラインメトリクスを集めることを前提にしています。そのためCircleCI CLIなどを事前に設定し、スキル自体が CircleCI からライブでメトリクスを取得する仕組みを用意することで、データに基づいた分析が行えます。もし計測を行う準備がないリポジトリを対象とする場合は、config.yml の静的解析を重点的に行います。

診断から修正 PR まで任せる

config スキルのレビュー結果から続けて「修正の PR を作ってください」と依頼することもできます。

❯ はい。gh cliを使ってprを作ってください。

  Ran 1 shell command

⏺ Update(.circleci/config.yml)
Added 1 line, removed 1 line
    docker:
      - image: cimg/node:22.14
    resource_class: medium
    parallelism: 4
    parallelism: 2
    steps:
      - checkout
      - node/install-packages:

  Ran 1 shell command

Committed 2fbd2ac, pushed to reduce-parallelism-2, created PR #2

変更は parallelism: 4 を parallelism: 2 に置き換える 1 行だけで、診断で示された結論がそのまま diff に反映されています。ブランチ名（reduce-parallelism-2）で変更意図がわかるようになっており、レビューして問題なければマージできる状態で PR が作られました。

ここまでを通すと、診断・提案・適用・PR 作成までを一連の依頼でエージェントに任せられることがわかります。ただし PR はあくまで提案です。前述のとおり診断は手元の実測に依存するため、適用してよいかどうかの最終判断は人が行い、レビューのうえでマージしてください。

まとめ

CircleCI の公式スキルを Claude Code に導入すると、/circleci:config に .circleci/config.yml を渡すだけで、ボトルネックの要約から根拠つきの変更提案、想定効果、検証・切り戻し手順までを 4 部構成で受け取れます。今回の例では、並列数を増やしても速くならない構造を指摘し、parallelism を 4 から 2 へ下げる提案から PR 作成までを任せられました。

このようにCircleCIのスキルやCLIなどを活用することで、AIエージェントにCIの設定や現状について相談しやすくなります。実際のデータに基づいた分析なども、CircleCIが用意している CLI / APIなどでエージェントが収集可能ですので、ぜひ単発の分析ではなく、定期的な診断タスク化までご検討ください。

次のステップ

Claude Code で /plugin marketplace add CircleCI-Public/skills を実行してマーケットプレイスを登録する
/plugin install circleci@circleci-public-skills でプラグインをインストールし、/reload-plugins で有効化する
/circleci:config に自分の .circleci/config.yml の診断を依頼する
提案の根拠を確認し、必要なら PR 作成まで依頼する