APMでClaude CodeとCodexのスキルを一元管理してみた

はじめに

Claude Code と Codex を併用していると、設定ファイルの管理に悩まされがちです。プロジェクトごとに .claude/rules/ や AGENTS.md、スキル（.claude/skills/ や .agents/skills/）、カスタムエージェント定義などを、各ツールの仕様に合わせて二重管理する手間がかかります。

Microsoft の Agent Package Manager（APM） は、AI コーディングエージェント向けパッケージマネージャーです。設定やスキルを apm.yml で一元管理し、apm install を実行することで、各ツールの配置先やファイル形式に合わせて自動展開してくれます。実際に試したところ、1 つのパッケージから Claude Code と Codex の両方へ、スキルやエージェント定義をスムーズに配置できました。

両ツールで執筆ルールやスキルを共有するため、本記事のリポジトリにも APM を導入しました。そこで本記事では、公式 Quickstart と GitHub リポジトリをもとに、APM の基本的な仕組みと導入手順を解説します。また、Claude Code と Codex へのファイル配置、ロックファイルによる環境再現、改ざん検知（audit）の検証結果を紹介します。あわせて、更新管理、パッケージ配布、CI 連携といった実践的な機能についても公式資料をもとにまとめました。

また、自作プラグインにおいて「共通基準・個別機能・利用環境」の 3 層に責務を分けた構成例についても紹介します。

主に次の公式ドキュメントを参照しました。

Agent Package Manager（APM）とは

APM は、AI コーディングエージェント向けの設定を一元管理するパッケージマネージャーです。スキル、インストラクション、プロンプト、エージェント定義、フック、MCP サーバーや LSP サーバーの設定などをまとめて管理できます。各ツールの仕様に合わせて、ファイルの配置や設定の登録を自動で行ってくれます。

Claude Code と Codex では設定ファイルの配置場所や形式が異なります。APM は .apm/ 配下の共通レイアウトや、対応するツールのプラグイン形式からリソースを読み取り、apm.yml の宣言に基づいて各ツールの仕様に合わせた形式に変換・配置します。

フックの設定と、呼び出すスクリプトの配置先は別です。パッケージ内のフックスクリプトは .claude/hooks/ や .codex/hooks/ などへ配置されます（詳細は公式ドキュメントの Hooks and commands を参照）。

これらを含むパッケージやプラグインを apm.yml に宣言すると、APM が推移的な依存関係まで自動で解決し、各ツール向けに配置してくれます。パッケージが別のパッケージに依存している場合も、依存先までまとめてインストールされます。

配置方法はプラグインの形式によっても異なります。例えば Agent Plugins v1 形式は、v0.33.0 では Copilot 向けにプラグイン全体を登録し、apm_modules/ から読み込ませる仕様です。この形式は Claude Code や Codex 向けの個別ファイルには展開されません。利用時には GitHub Copilot CLI 1.0.81 以上が必要です（詳細は公式ドキュメントの Install Agent Plugins for Copilot を参照）。

公式 README が挙げる 3 つの特徴

公式の README は、APM の特徴を次の 3 つに整理しています。

1. マニフェストによる共有（Portable by manifest）: apm.yml で依存関係を宣言し、apm.lock.yaml で解決したコミットやハッシュを記録します。Claude Code なら .claude/、Codex なら .codex/ と .agents/、GitHub Copilot なら .github/ など、各ツールに対応する場所へ配置します。
2. 既定のセキュリティ検査（Secure by default）: インストール前の隠し Unicode 文字の検査や、ロックファイルによる整合性の確認を行います。間接依存パッケージが宣言する自前定義の MCP サーバーには、後述する信頼確認もあります。
3. ポリシーによる管理（Governed by policy）: 組織が apm-policy.yml で、インストールを許可するパッケージの取得元や管理対象の種類などを制限できます。

apm install や apm compile が終わると、APM のプロセスは終了します。配置されたファイルを読み込んで実行するのは、各 AI ツール（Claude Code や Codex など）自身です。

コマンド体系や操作感は npm と似ており、依存関係の追加や更新を直感的に行えます。

Git リポジトリをパッケージの取得元として直接利用できるため、マーケットプレイスへの登録は必須ではありません。README によると、GitHub、GitLab、Bitbucket、Azure DevOps、GitHub Enterprise、Gitea など幅広いホストに対応しています。

前提条件・検証環境

• 検証日と公式資料の確認日: 2026 年 10 月 8 日
• OS: macOS（Apple Silicon）
• APM: 0.33.0（PyPI の apm-cli を uv の一時環境で実行）
• サンプル: microsoft/apm-sample-package#v1.0.0
• 配置先: Claude Code と Codex

検証時点の最新リリースは v0.33.0 です。公式サイトに加え、v0.33.0 のドキュメントとソース（APM v0.33.0 Release）も照合しました。以下のログは、このバージョンで取得したものです。

確認した範囲は、CLI によるファイルの配置、AGENTS.md の生成、ロックファイルからの復元、監査、削除時の保護までです。各 AI ツール上でのスキルやエージェントの呼び出し、フックの実行、MCP サーバーへの接続は検証していません。

やってみた

公式の Quickstart の導入手順は、APM のインストール、プロジェクトの初期化、パッケージのインストールの 3 段階です。ここでは公式のサンプルパッケージ microsoft/apm-sample-package を Claude Code と Codex の両方に配置し、その後にロックファイルによる再現性と改ざん検知の挙動を確認します。

手順 1: APM をインストールする

macOS では Homebrew でインストールできます。現在は専用 tap の追加は不要です。

brew install apm

今回の検証では既存の CLI 環境と分けるため、uv を使って PyPI 版の 0.33.0 を指定しました。uv が使える環境では、次のコマンドで同じバージョンを起動できます。

uv tool run --from apm-cli==0.33.0 apm --version

Agent Package Manager (APM) CLI version 0.33.0

以降のコマンドでは、uv tool run --from apm-cli==0.33.0 apm を apm と略記します。

Homebrew を使わない場合は、環境に応じて次のいずれかでインストールできます（詳細は公式の Installation ガイドを参照）。

# Linux / macOS
curl -sSL https://aka.ms/apm-unix | sh

# pip（Python 3.10 以上）
python3 -m pip install apm-cli

# Windows
irm https://aka.ms/apm-windows | iex

手順 2: apm init でプロジェクトを作る

空のディレクトリで apm init を実行すると、apm.yml が生成されます。公式 Quickstart は apm init my-agent でディレクトリも新規作成する例ですが、ここではディレクトリを先に用意しました。-y を付けると対話プロンプトを省略できます。

mkdir demo && cd demo
git init
apm init -y

生成された apm.yml は次のとおりです。

name: demo
version: 1.0.0
description: APM project for demo
author: akito
# Which agent platforms to deploy to (uncomment to pin):
# targets:
#   - copilot
#   - claude

dependencies:
  apm: []
  mcp: []
includes: auto
scripts: {}

必須項目は name と version だけです。targets をコメントアウトしたままにすると、.claude/ や .codex/ などのディレクトリの有無から配置先が自動検出されます。

Quickstart では、最初に把握しておく項目として次の 3 つを挙げています。

includes: auto は、そのプロジェクトから配るファイルを自動検出する設定です。.apm/ がある場合はその内容を使い、ない場合はルートにある対応済みのプラグイン用ディレクトリを使います。

手順 3: パッケージをインストールする

パッケージの追加は apm install <owner>/<repo> で行います。初期化直後はプロジェクト内に .claude/ も .codex/ も存在しないため、--target オプションで配置先を指定しました。

Quickstart と同様に v1.0.0 タグを指定し、配置先を Claude Code と Codex に設定します。タグやコミット SHA を指定しておくと、インストールされる内容が固定され安全です。

apm install microsoft/apm-sample-package#v1.0.0 --target claude,codex

[*] Validating 1 package...
[i] GitHub API rate limit hit while checking github.com; skipping the pre-flight accessibility probe and letting the
download step confirm the package
[*] Updated apm.yml with 1 new package(s)
[>] Installing 1 new package...
[>] Resolving microsoft/apm-sample-package...
[>] Resolving awesome-copilot-review-and-refactor...
[i] Targets: claude, codex  (source: --target flag)
  [+] microsoft/apm-sample-package #v1.0.0 @fb285168
  [+] github.com/github/awesome-copilot/skills/review-and-refactor #default @7cce7cfb
  |-- 2 agents integrated -> .claude/agents/, .codex/agents/
  |-- 2 commands integrated -> .claude/commands/
  |-- 1 rule(s) integrated -> .claude/rules/
  |-- 1 skill(s) integrated -> .agents/skills/, .claude/skills/
  |-- Skill integrated -> .agents/skills/, .claude/skills/
[i] Added apm_modules/ to .gitignore
[i] Instructions installed for codex. Run 'apm compile' to update AGENTS.md.
  [!] [apm-sample-package] Claude command accessibility-audit: frontmatter keys not supported for claude commands and
were dropped: mode. Supported keys: allowed-tools, argument-hint, description, input, model.
  [!] [apm-sample-package] Claude command design-review: frontmatter keys not supported for claude commands and were
dropped: mode. Supported keys: allowed-tools, argument-hint, description, input, model.
  [!] 1 dependency unpinned: github/awesome-copilot -- add #tag or #sha to prevent drift
[*] Installed 2 APM dependencies in 13.4s.

初回のインストール所要時間は 13.4 秒でした。途中で GitHub API のレート制限に関する案内が表示されましたが、パッケージの取得と配置は無事に完了しています。

実行ログから、次の挙動が確認できます。

• サンプルパッケージが依存する github/awesome-copilot のスキルも、推移的な依存として一緒にインストールされた
• apm.yml の dependencies.apm にパッケージが追記され、依存の実体を置く apm_modules/ が .gitignore に追加された
• Claude Code のコマンドへ変換する際、未対応の frontmatter キー（mode）が警告とともに対象外になった
• Codex 向けの指示については、apm compile で AGENTS.md に集約するよう案内が表示された
• 参照先を固定していない推移的な依存（github/awesome-copilot）には、ドリフトを防ぐため #tag か #sha を付けるよう警告が出た

手順 4: 配置されたファイルを確認する

配置されたファイルは次の 9 ファイルです。依存パッケージの実体が入る apm_modules/ は除いています。

.agents/skills/review-and-refactor/SKILL.md
.agents/skills/style-checker/SKILL.md
.claude/agents/design-reviewer.md
.claude/commands/accessibility-audit.md
.claude/commands/design-review.md
.claude/rules/design-standards.md
.claude/skills/review-and-refactor/SKILL.md
.claude/skills/style-checker/SKILL.md
.codex/agents/design-reviewer.toml

パッケージ側のソースは .apm/ ディレクトリに種類ごとに置かれています。

apm-sample-package/
├── apm.yml
└── .apm/
    ├── agents/design-reviewer.agent.md
    ├── instructions/design-standards.instructions.md
    ├── prompts/accessibility-audit.prompt.md
    ├── prompts/design-review.prompt.md
    └── skills/style-checker/SKILL.md

ソースと配置先を見比べると、APM が各ツールの仕様差を吸収し、適切な形式に変換して配置していることがわかります。

特に注目したいのが、エージェント定義の形式変換と指示（instructions）の集約方法の違いです。

APM は .apm/agents/ の共通 Markdown 定義を、Claude Code 向けには Markdown、Codex 向けには TOML として配置します。Codex 向けのファイルでは、Markdown 本文が developer_instructions に格納されました。次は本文を省略した抜粋です。

name = "design-reviewer"
description = "A design review specialist that enforces design system standards"
developer_instructions = "# Design Reviewer\n\nYou are a design review specialist. ..."

Codex 向けの TOML には name、description、developer_instructions が展開されますが、エージェントごとのモデル指定や推論 effort（Codex の model_reasoning_effort など）といった設定項目は含まれません。

また、APM は Claude Code 向けの指示を .claude/rules/*.md へ個別に配置します。一方、Codex 向けには個別のルールファイルを置かず、apm compile コマンドで AGENTS.md に集約します。次のコマンドを実行し、サンプルの設計基準がルートの AGENTS.md に書き込まれることを確認しました。

apm compile --target codex

AGENTS.md が 1 ファイル生成されました。サンプルの指示ファイルの frontmatter に description がないという警告も出ましたが、生成自体は正常に完了しています。

APM 0.33.0 の Codex 向け配置では prompts と commands は対象外です。スキルについては、.claude/skills/ と .agents/skills/ の両方に SKILL.md が配置されました。

配置先の対応表は公式ドキュメントの Targets matrix にまとまっています。

どの配置先が有効かは apm targets で確認できます。

apm targets

  TARGET       STATUS     SOURCE                                   DEPLOY DIR
  ------------ ---------- ---------------------------------------- ----------
  claude       active     .claude/                                 .claude/
  copilot      inactive   needs .github/copilot-instructions.md    .github/
  cursor       inactive   needs .cursor/                           .cursor/
  codex        active     .codex/                                  .codex/
  gemini       inactive   needs GEMINI.md                          .gemini/
  grok-build   inactive   needs .grok/                             .grok/
  opencode     inactive   needs .opencode/                         .opencode/
  windsurf     inactive   needs .windsurf/                         .windsurf/
  kiro         inactive   needs .kiro/                             .kiro/

この出力では 9 つの配置先が並び、Claude Code と Codex が active になりました。明示指定で使える配置先もあるため、この一覧が対応する配置先のすべてではありません。

手順 5: ロックファイルから同じ環境を再現する

インストール後には apm.lock.yaml が生成されます。抜粋すると次のとおりです。

lockfile_version: '1'
apm_version: 0.33.0
dependencies:
- repo_url: microsoft/apm-sample-package
  name: apm-sample-package
  host: github.com
  resolved_commit: fb2851683be0e0e7711421d518bd8dba23b0b1f6
  resolved_ref: v1.0.0
  version: 1.0.0
  package_type: apm_package
  deployed_files:
  - .agents/skills/style-checker
  - .agents/skills/style-checker/SKILL.md
  - .claude/agents/design-reviewer.md
  # ...
  deployed_file_hashes:
    .claude/agents/design-reviewer.md: sha256:6169887...
    # ...
  content_hash: sha256:744cca5...
# ...
deployments:
- kind: project-relative
  target: claude
  value: .claude/agents/design-reviewer.md
  runtime: null
  scope: project
  owners:
  - microsoft/apm-sample-package
  active_owner: microsoft/apm-sample-package
  content_hash: sha256:6169887...
# ...

解決したコミット SHA、配置したファイルの一覧、各ファイルの SHA-256 ハッシュが記録されています。0.33.0 では、配置先とその所有パッケージを表す deployments が配置記録の正本です。依存ごとの deployed_files と deployed_file_hashes も、互換用の情報として出力されます^[1]。

タグを指定していない推移的な依存も、ロックファイルではコミットが固定されていました。

apm.yml と apm.lock.yaml だけを別のディレクトリにコピーし、--frozen でインストールしてみます。コピーには手順 3 のインストール直後のファイルを使いました。チームメンバーがリポジトリを clone した直後や、CI で環境を作る場面を想定しています。

apm install --frozen --target claude,codex

[*] Installed 2 APM dependencies in 3.1s.
[i] Lockfile presence verified. Run 'apm audit' for on-disk content integrity.

.claude/、.codex/、.agents/ に配置された 9 ファイルの SHA-256 を比較したところ、元の環境とすべて一致しました。apm.lock.yaml の内容も変わっていません。所要時間は 3.1 秒で、ローカルキャッシュが効率よく活用されました。

復元先で apm audit --ci --no-policy を実行すると、10 項目すべてに合格し、終了コードは 0 でした。Codex 向けの AGENTS.md を復元先でも生成する場合は、続けて apm compile --target codex を実行します。

Quickstart では、次のファイルを Git で共有する運用を推奨しています。

生成した AGENTS.md も共有対象です。配置先のファイルをコミットしておけば、clone 直後から各 AI ツールがファイルを検出できます。ただし、ファイルが存在するだけでは各機能を完全に実行できるとは限りません。依存スクリプトやリファレンスへの参照を復元するためにも、clone 後はリポジトリのルートで apm install を実行しましょう。

手順 6: apm audit で改ざんを検知する

配置したファイルを意図的に書き換えて、apm audit で検知できるかを試しました。

echo "tamper" >> .claude/rules/design-standards.md
apm audit

[>] Scanning installed packages and deployed files...
[>] Replaying install (cache-only)...
[+] Replayed 2 package(s)
[>] Diffing scratch vs working tree...
[!] Drift detected: 1 file(s)

[*] 10 file(s) scanned -- no issues found

[x] Drift detected: 1 file(s)

  modified (1):
    - .claude/rules/design-standards.md  [microsoft/apm-sample-package]

  [i] Run 'apm install' to re-sync deployed files with the lockfile.

公式ドキュメント（apm audit）によると、apm audit はキャッシュから作業用ディレクトリへインストールを再現し、現在のファイルとの差分を検出します。書き換えたファイルと、その由来となったパッケージ名が表示されました。no issues found は隠し Unicode 文字の検査結果であり、差分がないという意味ではありません。

このとき、通常の apm audit の終了コードは 0 でした。既定では差分の検知だけでは失敗扱いにならないため、CI で変更をブロックするには --ci を使います。組織ポリシーの検証を分けるため、ここでは --no-policy も付けました。

apm audit --ci --no-policy

実行結果では content-integrity と drift の 2 項目が失敗となり、終了コードは 1 でした。組織ポリシーも適用する運用では --no-policy を外します。

続けて、書き換えたままの状態でパッケージを削除してみました。

apm uninstall microsoft/apm-sample-package

Retained user-edited file .claude/rules/design-standards.md from
microsoft/apm-sample-package; resolve it and retry.
[i] Cleaned 8 stale files from microsoft/apm-sample-package
[i] Cleaned 4 stale files from github/awesome-copilot/skills/review-and-refactor
[x] Uninstall could not remove tracked target files; manifest and lockfile
ownership were preserved. Package directories may already have been removed.
[x]   - .claude/rules/design-standards.md
[x] Resolve or remove the listed files, then retry uninstall.

削除対象のうち、手で編集したファイルが保護されたため、コマンドは終了コード 1 で停止しました。apm.yml とロックファイルの内容も変更されずに維持されます。依存パッケージの実体や未編集の配置ファイルは、この時点で削除されています。

今回は検証用に追記した内容なので、残ったファイルを確認して削除し、apm uninstall を再実行すると終了コード 0 で完了しました。なお、別途 apm compile で生成した AGENTS.md は残るため、依存関係の削除後はコンパイル結果も見直します。

スキルやプラグインを依存に追加する書き方

ここから「更新・配布・CI で使う機能」までのコマンドや設定例は、公式ドキュメントに基づく機能紹介です。これらの例のインストールや接続、更新、配布、CI 実行は検証していません。

リポジトリやサブディレクトリを指定する

サンプルパッケージ以外にも、スキルを置いたサブディレクトリ、プラグイン、単一のエージェント定義などを指定できます。公式 README には、次のような依存の指定例が載っています。

dependencies:
  apm:
    - anthropics/skills/skills/frontend-design
    - github/awesome-copilot/plugins/context-engineering
    - github/awesome-copilot/agents/api-architect.agent.md
    - microsoft/apm-sample-package#v1.0.0

自分で作ったスキルを配布する場合も、Git リポジトリにあれば依存として指定できます。apm.yml の依存は owner/repo/path#ref の形式で書きます。公式の Manifest schema を参考に、以下に参照先の指定方法をまとめました。

dependencies:
  apm:
    - microsoft/apm-sample-package                # 参照先を省略（ロックファイルでコミットを固定）
    - microsoft/apm-sample-package#v1.0.0         # タグを固定
    - microsoft/apm-sample-package#main           # ブランチ（内容は変わりうる）
    - gitlab.com/acme/coding-standards            # GitHub 以外のホスト
    - ComposioHQ/awesome-claude-skills/brand-guidelines   # サブディレクトリ
    - contoso/prompts/review.prompt.md            # 単一ファイル
    - ./packages/my-shared-skills                 # ローカルパス

既定の設定では、ホストを省略すると GitHub のリポジトリとして扱われます。リポジトリ内のサブディレクトリだけを取り出せるため、1 つのリポジトリに複数のスキルをまとめて管理し、必要なものだけを各プロジェクトに入れる運用ができます。

スキルを選択する・ユーザー共通で配置する

複数のスキルを含むパッケージから、--skill で必要なものだけを選べます。README の例では、次のように deploy-to-vercel を指定しています。

apm install vercel-labs/agent-skills --skill deploy-to-vercel

選択したスキルは apm.yml に保存されます。同じパッケージに別の --skill を指定すると選択が追加され、--skill '*' で全スキルの指定に戻せます。

複数のプロジェクトで共通のスキルを使いたい場合は、apm install --global <パッケージ> でユーザー単位に配置できます。この場合は ~/.apm/apm.yml とロックファイルで依存を管理し、各ツールのユーザー向けディレクトリへ配置します。チームで共有する設定はプロジェクト単位、個人で共通利用する設定はユーザー単位、と使い分けられます（オプションの詳細は apm install リファレンス を参照）。

マーケットプレイスからインストールする

公式ドキュメント（Installing from marketplaces）によると、マーケットプレイスに掲載されたプラグインも APM から取得できます。まずカタログを登録し、<パッケージ名>@<マーケットプレイス名> で指定します。公式 README には次の例があります。

apm marketplace add github/awesome-copilot
apm install azure-cloud-development@awesome-copilot

この経路でも、APM のロックファイル、推移的な依存解決、配置前の検査、apm audit による監査を利用できます。各 AI ツールのネイティブなプラグインインストール機能だけを使う場合は、APM のロックファイルによる依存の固定や、配置履歴に基づく差分監査は利用できません。

MCP サーバーを宣言する

MCP サーバーも dependencies.mcp で宣言できます。次は README にある宣言例です。

dependencies:
  mcp:
    - name: io.github.github/github-mcp-server
      transport: http

認証が必要なサーバーでは、別途そのサーバーに合わせた設定が必要です。マニフェスト内で環境変数を参照する場合は ${VAR} や ${env:VAR} を使います。APM 自体は GitHub Actions の ${{ ... }} テンプレートを評価しません。

LSP サーバーを宣言する

公式ドキュメントの Install LSP servers によると、LSP（Language Server Protocol）サーバーの設定も dependencies.lsp で管理できます。v0.33.0 では Claude Code と GitHub Copilot CLI 向けに設定を生成します。Go の言語サーバー gopls を宣言する例は次のとおりです。既存の apm.yml に追加する部分だけを示しています。

dependencies:
  lsp:
    - name: gopls
      command: gopls
      args: ["serve"]
      extensionToLanguage:
        ".go": go

gopls 本体は別途インストールし、PATH から実行できるようにします。APM が行うのは各ツールの接続設定です。プロジェクト単位では、Claude Code に .claude/skills/apm-lsp/.claude-plugin/plugin.json、Copilot CLI に .github/lsp.json を生成します。

Claude Code は 2.1.157 以上が必要です。リポジトリのルートから起動してワークスペースを信頼し、設定後は再起動または /reload-plugins を実行します。同じ拡張子を扱う LSP が既にある場合も含め、対象ファイルで診断や定義への移動が使えるかを確認します。

更新・配布・CI で使う機能

依存関係を確認して更新する

公式ドキュメントの Update and refresh によると、通常の apm install は、宣言が変わっていない依存についてロック済みのコミットを再現します。新しいコミットやバージョンへの更新には、apm update を使います。

apm update は apm.yml の参照先やバージョン条件を満たす範囲で再解決します。例えば #v1.0.0 とタグを固定している依存を v2.0.0 に上げたい場合は、apm.yml の参照先も書き換えます。APM CLI 本体の更新には、インストール方法に応じて brew upgrade apm などを使います。

ZIP にまとめて配布する

パッケージを作る側には、設定と依存関係を配布用のバンドルにまとめる apm pack があります（詳細は Pack a bundle を参照）。README では、Copilot、Claude Code、Cursor 向けのプラグインを作る用途も紹介されています。apm.yml を持つ配布元のプロジェクトで実行し、--archive を付けると ZIP として出力できます。

apm pack --archive -o ./dist

受け取った側は、配布されたファイルのパスを指定して apm install ./my-pkg-1.0.0.zip のようにインストールします。ZIP には plugin.json、スキルなどのファイル、ロックファイルが含まれ、インストール時にファイルのハッシュや不足・追加を検査します。

既定の出力は Claude Code のプラグイン形式です。--format agent-plugin を指定すると Agent Plugins v1 形式になりますが、この形式で表現できるのはスキルと MCP 設定などに限られます。エージェント定義やフック、LSP 設定などを含むソースはエラーになるため、配布先と含めたい機能に合わせて形式を選びます。

ロックファイルから SBOM を出力する

SBOM（Software Bill of Materials）は、利用するソフトウェア部品の一覧です。APM は apm.lock.yaml から CycloneDX または SPDX 形式で出力できます（詳細は apm lock リファレンス を参照）。

apm lock export --format cyclonedx --output apm-sbom.cdx.json
apm lock export --format spdx --output apm-sbom.spdx.json

出力はロックファイルに記録された依存の一覧で、実ファイルの再ハッシュや通信は行いません。構成の棚卸しに使い、配置済みファイルのハッシュの差分や隠し Unicode 文字は apm audit で別途確認します。

SLSA（Supply-chain Levels for Software Artifacts）は、ソフトウェアの生成・配布過程を保護するためのガイドラインです。SLSA の来歴情報（provenance）は、成果物がどこで、いつ、どのように生成されたかを検証できる形で記録します^[2]。APM が出力する SBOM に、署名や SLSA の来歴情報は含まれません。

非公開リポジトリの認証を確認する

非公開リポジトリには、そのリポジトリを読めるトークンや Git の認証ヘルパーを使います。GitHub では GITHUB_APM_PAT、GitLab では GITLAB_APM_PAT などの環境変数を指定できます。認証情報はローカルの環境変数や CI のシークレットで管理し、apm.yml には記載しません。

v0.33.0 で追加された apm auth は、利用できる認証情報を確認し、見つからなければ作成方法を案内します（詳細は apm auth リファレンス を参照）。--check を付けると、ホストの REST API にアクセスして有効性も確認します。

apm auth github.com --check
apm auth gitlab.com --check

対応するホストは GitHub、GitHub Enterprise Server、GitLab です。自社運用のホストでは、GITHUB_HOST や GITLAB_HOST などでホスト種別も設定します。MCP サーバーへの接続認証は、Git リポジトリの取得認証とは別に設定します。

GitHub Actions で監査する

公式の microsoft/apm-action を使うと、GitHub Actions に APM CLI をセットアップできます（詳細は APM in CI/CD や apm-action のリポジトリ を参照）。配置済みのファイルをコミットしているリポジトリでは、setup-only: true を指定し、チェックアウトしたファイルを apm audit --ci で監査する構成が紹介されています。

name: APM audit
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: microsoft/apm-action@v1
        with:
          apm-version: '0.33.0'
          setup-only: true
      - name: Audit deployed files
        run: apm audit --ci
        env:
          GITHUB_TOKEN: ${{ github.token }}

監査前に通常の apm install を実行すると、検出したい変更が再配置で上書きされる可能性があります。setup-only では CLI のセットアップだけを行い、監査に必要な依存は apm audit --ci がロックファイルに従って作業用ディレクトリへ復元します。

この例の ${{ github.token }} は GitHub Actions が評価します。別の非公開リポジトリを取得する場合は、対象を読めるトークンをシークレットに保存し、GITHUB_APM_PAT などで監査ステップへ渡します。AGENTS.md の生成結果も検査する場合は、監査後に依存を復元して apm compile --target codex を実行し、Git の差分を確認するチェックを追加します。

APM のセキュリティ機能

AI コーディングエージェントは、配置された指示やスキルを読み取って動作します。読み込みタイミングはツールごとに異なりますが、配置したファイルはエージェントから参照される可能性があります。

そのため公式ドキュメントでは、"File presence IS execution."（ファイルが存在すること自体が実行である） と警告されています^[3]。悪意のあるプロンプトや隠し指示が配置されると、ユーザーが気付かないまま不正動作を引き起こす恐れがあります。こうした危険を防ぐため、APM は配置前の静的検査を重視しています。

主な機能は次のとおりです。

• 隠し Unicode 文字の検査: タグ文字や双方向制御文字など、エディタ上で見えない不可視文字によるプロンプトインジェクションを検出します。重大な問題が見つかった場合は配置を中断します。
• 間接依存の自前定義 MCP のブロック: 深さ 2 以上のパッケージが宣言する独自 MCP サーバー（registry: false）は、既定では追加されません。利用するには自前の apm.yml で再宣言するか、--trust-transitive-mcp で許可します。
• 実行ファイルの承認ゲート: ゲートが有効な場合、パッケージに含まれるフックや実行スクリプト（bin/）、自前定義の MCP サーバー、LSP サーバーなどは、承認されるまで配置されません。

MCP のブロックは、v0.33.0 の実装では上記の条件に限定されます。直接依存パッケージ（深さ 1）が宣言する自前定義 MCP と、レジストリ参照の MCP は、この判定ではブロックされません。これらにも、別途、実行ファイルの承認ゲートや組織ポリシーによる制限が適用されます^[4]。

実行ファイルの承認ゲートは、主に次の条件で有効になります。

• プロジェクトの apm.yml に executables を宣言する。空の executables: {} でも有効になる
• 組織ポリシーの executables に拒否・必須・推奨などの設定がある
• ユーザー設定 ~/.apm/config.json の executables.deny に拒否設定がある

ユーザー側の executables.allow だけでは、ゲートは有効になりません。互換用の旧設定 allowExecutables や、組織ポリシーの bin_deploy の拒否設定も有効化の判定に含まれます。どの条件にも該当しない場合は、後方互換性のためゲートは無効です。本記事では、v0.33.0 のソースコードと、ユーザー側の拒否設定だけで有効化されることを確かめたテスト定義を参照しています^[5]。

実行ファイルの許可と拒否は、次のように apm.yml に書きます（コマンドによる設定方法は apm approve リファレンス を参照）。

executables:
  allow:
    "owner/repo#1.2.0":
      hooks: true
      bin: true
  deny:
    "evil/pkg":
      hooks: true
      mcp: true

このリポジトリでも、執筆用スキルに付属する記事チェック用のフックと CLI を executables.allow で許可しています。フックはエージェントの操作に合わせてシェルコマンドを実行します。そのため、パッケージの中身を確認したうえで許可するのが安全です。

依存関係のタグやコミット SHA は dependencies.apm で固定します。公式の apm approve リファレンスによると、通常の依存パッケージでは、承認キーを owner/repo#1.2.0 と書いても許可はパッケージ単位で一致し、そのバージョンだけに限定されません。依存関係の固定と実行ファイルの許可は、別々に確認する必要があります。

Codex 向けフックの配置も確認する

v0.33.0 では、Codex 向けのフックがネイティブの JSON 形式で出力されます。そこで、ローカルに .apm/hooks/hooks.json を用意し、フックの配置を確認しました。

{
  "hooks": {
    "PostToolUse": [
      { "type": "command", "command": "echo apm-hook-example", "timeout": 10 }
    ]
  }
}

利用側の apm.yml に executables: {} を宣言してインストールすると、フックは未承認として保留され、.codex/hooks.json は作られませんでした。承認後に再インストールすると、Claude Code には .claude/settings.json、Codex には次の .codex/hooks.json が生成されました。

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          { "type": "command", "command": "echo apm-hook-example", "timeout": 10 }
        ]
      }
    ]
  }
}

Codex 向けには、イベント配下に hooks 配列を持つグループが追加されています。ここで確認したのは承認による配置制御と JSON の生成までです。Codex 上でイベントを発火させる検証は行っていません。

なお、承認後の再インストールでも保留を示す案内が残りました。apm approve --pending では未承認のパッケージはなく、apm approve --list でも hooks[+:project-allow] を確認できました。今回は案内だけで判断せず、承認状態と生成されたファイルを照合しています。

組織向けには、apm-policy.yml で利用できるパッケージや MCP サーバーを制限するポリシー機能もあります（詳細は Policy Files を参照）。ただし執筆時点のドキュメントでは Experimental（early preview）扱いです。

3層に分けてプラグインを組み合わせる

APM ではパッケージ間の依存関係を定義できます。この仕組みを活用し、プラグインを 3 つの階層に分けて運用する構成も試しています。

依存関係の向きは、次のようになります。

機能層のパッケージは、必要な共通層を dependencies.apm に宣言します。環境層は機能層に依存し、利用側のプロジェクトは環境層を指定します。APM が推移的な依存関係まで解決するため、マニフェストを書くだけで共通層まで自動取得できます（詳細は Manage dependencies を参照）。

共通の基準を各プラグインへコピーせず、複数の機能から参照できる点が、この分け方で APM を使う利点です。用途ごとの組み合わせは環境層にまとめることで、共通の基準や個別の機能を保ちながら、プロジェクトに必要な構成を選べます。

この 3 層構成は、プラグインの責務を分けるために試しているアプローチです。APM が要求する固定の階層ではなく、パッケージ間の依存関係を利用した組み立て方の一例になります。

気になったところ

実際に触って気になった点を挙げます。

1 つ目は、--target で指定した配置先が apm.yml に保存されない点です。手順 3 で --target claude,codex を付けても、apm.yml の targets はコメントアウトされたままでした。自動検出に頼らず配置先を固定したい場合は、apm.yml に targets: を明記しておくのが確実です。

2 つ目は、ツールごとに APM の対応範囲が異なる点です。サンプルの prompts は Claude Code 向けのコマンドに変換されますが、Codex には配置されません。また Claude Code 向けでも未対応の mode キーは除外されます。さらに、エージェント定義（.apm/agents/）を展開する際、エージェントごとのモデルや推論 effort（Codex の model_reasoning_effort など）は個別に選べません。1 つのパッケージで共通化を図る場合でも、各ツールの設定反映範囲を事前に確認しておくと安心です。

3 つ目は、監査結果の画面表示と終了コードの違いに注意が必要な点です。通常の apm audit は差分を検出しても、終了コード 0 で正常終了することがあります。そのため、CI で差分を検知してビルドを止めたい場合は apm audit --ci を指定します。

まとめ

今回は、Microsoft の Agent Package Manager（APM）を使い、サンプルパッケージを Claude Code と Codex に配置し、ロックファイルからの再現と apm audit による改ざん検知を試しました。

Claude Code と Codex を併用している環境では、.claude/ や .codex/、AGENTS.md にまたがる設定の一元管理に役立ちます。特に、各ツールの形式差を APM が自動で吸収してくれる点や、編集済みファイルの保護設計には安心感があります。利用時は、対応機能やプラグイン形式、承認ゲートの有効化条件を把握し、導入内容とバージョンを確認してから許可する運用が大切です。

また APM には、依存関係の更新、マーケットプレイス、ZIP 配布、SBOM 出力、CI 監査といった機能も揃っています。設定を安全かつ継続的に管理できるため、チームの運用方針に合わせて段階的に取り入れられます。

本ブログが、Claude Code や Codex でスキルやルールを複数ツールでスマートに共有・管理したい方の参考になれば幸いです。

クラスメソッドオペレーションズ株式会社について

クラスメソッドグループのオペレーション企業です。

運用・保守開発・サポート・情シス・バックオフィスの専門チームが、IT・AIをフル活用した「しくみ」を通じて、お客様の業務代行から課題解決や高付加価値サービスまでを提供するエキスパート集団です。

当社は様々な職種でメンバーを募集しています。

「オペレーション・エクセレンス」と「らしく働く、らしく生きる」を共に実現するカルチャー・しくみ・働き方にご興味がある方は、クラスメソッドオペレーションズ株式会社 コーポレートサイト をぜひご覧ください。※2026年1月 アノテーション㈱から社名変更しました