Claude Code のスキルをチームで共有して、全員で育てる仕組みを作った

想定読者

Claude Code をすでに使い始めているが、チームで設定を揃える方法を探している方
AI活用をチーム全体として推進したいが、標準化のアプローチが見えていない方

まとめ

これが正解と言うわけでもないし、一つのお試しである
Claude Code には「スキル」という機能があり、チームで共有・改善できる
共通スキル置き場 + apm（Agent Package Manager） を組み合わせれば、各リポジトリに apm install 一発で配布できる
GitHub Actions で定期実行すれば、スキルが毎日自動で最新化されてチーム全員に行き渡る
私たちはこの仕組みを skilltree という社内向けリポジトリで実践している

課題: チームのAI設定、バラバラになっていませんか？

Claude Code を使っていると、リポジトリごとに CLAUDE.md や設定がじわじわと育っていきます。詳しいメンバーのリポジトリには便利な設定が積み上がっているのに、別のリポジトリには何もない。

聞けば教えてもらえる、でもそれは何かのタイミングがないとなかなか起きない。

チームとして AI を活用しようとするとき、こういう「属人化した設定」の問題は早めに解決しておきたいところです。

Claude Code のスキルとは

Claude Code にはスキルという機能があります。

簡単に言うと、「/skill-name で呼び出せる専用プロンプト集」です。たとえば /code-review と打てば、プロジェクトのコードレビュー手順に沿った動作をする、という具合です。

スキルは .claude/skills/<スキル名>/SKILL.md という形式で管理されます。SKILL.md に書かれた指示が、/skill-name を呼んだときに Claude Code に渡されます。

便利な点は、このスキルをリポジトリに置いておくことで、チームメンバー全員が同じスキルを使えることです。

共通スキルの置き場所を作って、そこに集約する

個々のリポジトリで同じようなスキルを育てるのは非効率だし、改善が横展開されません。そこで、チーム全体で共有するスキルを一箇所に集めたリポジトリを作るというアプローチが効きます。改善を一箇所に閉じ込め、そこから各リポジトリへ配布したり個人の好みでインストールすることで、誰かの工夫がチーム全員に自動で行き渡るようになります。

私たちはこのアプローチを skilltree という社内リポジトリで実践しています。

https://github.com/voyagegroup/skilltree

現在は以下のようなスキルが置かれています。

find-skills-apm — 外部、内部からスキルを探して、導入がまだの場合はapmでinstallするコマンドを教えてくれる
init-apm — リポジトリへの apm 初期導入
init-skill-updater — skill-updater ワークフローの導入
create-issue — 社内の基本的なフローにしたがってissueを作成する
close-issue — 社内の基本的なフローにしたがってissueを閉じる
php-upgrade — PHP バージョンアップ作業の補助
composer-upgrade-audit — Composer 依存関係のアップグレード調査
cloud-cost — クラウドコスト分析

並びは fluct 固有の業務文脈を反映したものですが、「共通スキル置き場を用意してそこから各リポジトリに配布する」という設計の考え方そのものは、どんなチームでもそのまま使えます。重要なのは、改善を集約する場所をチームで一つ決めることです。

apm とはなにか

スキルの置き場所ができても、「どうやって各リポジトリに配布するか」という問題が残ります。手でコピーするのは論外として、Git のサブモジュールを使うのも管理が複雑になりがちです。

そこで使うのが apm（Agent Package Manager） です。

apm は Microsoft がオープンソースで開発している、AI エージェント向けの依存関係管理ツールです。npm や bundler を知っていれば、すぐにイメージが掴めます。

「package.json のような依存宣言ファイルを書けば、npm install 一発で必要なスキルが全部入る」

という仕組みが、AI エージェントの設定に向けて作られたものと考えてください。

依存関係は apm.yml というファイルに宣言します。

name: my-repo
version: 1.0.0
dependencies:
  apm:
    - voyagegroup/skilltree/.claude/skills/php-upgrade
    - voyagegroup/skilltree/.claude/skills/composer-upgrade-audit

このファイルをリポジトリに置いて apm install を実行すると、指定したスキルが .claude/skills/ に展開されます。(targetが複数あり .github/skills/ に展開すると言うことも可能です)

スキルのバージョンは apm.lock.yaml に固定されるので、チームメンバー全員が同じバージョンのスキルを使えます。

自リポジトリへの導入方法

実際の導入手順は次の通りです。

まず apm CLI をインストールします。詳細は apm の公式リポジトリを参照してください。

次に、リポジトリに apm.yml がない場合は初期化します。

apm init

apm.yml が生成されるので、使いたいスキルを dependencies.apm に追記します。

dependencies:
  apm:
    - voyagegroup/skilltree/.claude/skills/php-upgrade

最後に apm install を実行すれば完了です。

apm install

.claude/skills/php-upgrade/ が展開され、Claude Code で /php-upgrade が使えるようになります。

ちなみに共通スキル置き場の側に init-apm のような初期化スキルを置いておくと、Claude Code に「apm を導入して」と指示するだけで上記の手順を自動でやってくれるようになります。私たちは skilltree にこのスキルを置いていて、新しいリポジトリでの立ち上げが一気に楽になりました。

発展: 自動更新の仕組みも作った

apm を導入しても、スキルは随時改善・追加されるので、手動で apm install を実行しなければ各リポジトリのスキルが古いままになってしまいます。

そこで、GitHub Actions で定期的に自動更新する仕組みを作りました。skill-updater と呼んでいます。

仕組みはシンプルです。共通スキル置き場の側にコンポジットアクションを定義しておき（私たちの場合は skilltree の .github/actions/skill-updater/action.yml）、各リポジトリのワークフローからそれを呼び出す形にしています。

# .github/workflows/skill-updater.yml（各リポジトリに置くファイル）
name: Update Skills

on:
  schedule:
    - cron: '0 9 * * *'
      timezone: "Asia/Tokyo"
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  update-skills:
    runs-on: ubuntu-latest
    steps:
      - uses: voyagegroup/skilltree/.github/actions/skill-updater@main