apm-usage

APM（Agent Package Manager）

APM は、AI エージェントのスキル、指示、プロンプト、MCP サーバー向けの依存関係管理ツールです。エージェント設定向けの npm のようなものです。

このスキルが適用される場合

• 「このプロジェクトにスキルを追加する」
• 「スキルをグローバルにインストールする」
• 「このリポジトリ用のスキルを作成する」
• 「apm.yml をセットアップする」
• 「エージェントの依存関係を更新する」

基本コマンド

# Install all dependencies from apm.yml
apm install

# Install a specific package
apm install owner/repo
apm install owner/repo/skills/skill-name    # subdirectory skill
apm install owner/repo#v1.0.0               # pinned version

# Global (user-scope) install → ~/.claude/skills/
apm install -g owner/repo/skills/skill-name

# Update all to latest
apm install --update        # project scope
apm install -g --update     # global scope

# Remove
apm uninstall owner/repo
apm uninstall -g owner/repo

# Inspect
apm deps list               # project deps
apm deps list -g             # global deps
apm deps tree                # dependency tree
apm deps tree -g

# Security scan
apm audit

# Dry run (preview without changes)
apm install --dry-run

apm.yml マニフェスト

name: my-project
version: 1.0.0
# Deployment targets. APM 0.12+ requires this when no marker directory
# (.claude/ / .github/ / etc.) exists at the repo root. Declare it
# unconditionally to make the install reproducible.
targets:
  - claude
dependencies:
  apm:
    # GitHub shorthand
    - owner/repo
    - owner/repo#v1.0.0                  # pinned tag
    - owner/repo/skills/skill-name       # subdirectory

    # Non-GitHub hosts
    - gitlab.com/org/repo
    - git: [email protected]:org/repo.git
      path: skills/my-skill
      ref: main

    # Local path (dev only, not for -g)
    - ./packages/my-skill

  mcp:
    - io.github.github/github-mcp-server
scripts: {}

scripts: の例

scripts: は、名前からコマンドへのマップです。apm install 後のセットアップや、開発中に使用する単発タスクを登録します。

scripts:
  postinstall: "echo 'skills installed; restart Claude Code to pick them up'"
  verify: "ls -1 .claude/skills | sort"
  audit: "apm audit"

apm run <name> で実行します（例：apm run verify）。postinstall は apm install が成功すると自動的に実行されます（フック）。単発タスク（例：apm run audit）は明示的に呼び出す必要があります。

ロックファイル（apm.lock.yaml）のワークフロー

apm install によって apm.lock.yaml が生成されます。再現性を保証するには、次のようにします。

• プロジェクトスコープ：チームメイトが同じスキルバージョンを解決できるよう、apm.lock.yaml をコミットします。node_modules の package-lock と同じ考え方です。
• グローバルスコープ：新しいマシンでも同じバージョンをインストールできるよう、chezmoi 経由で ~/.apm/apm.lock.yaml を同期します。
• CI／新しいマシンでは、ロックファイルとの不一致があると失敗する apm install --frozen-lockfile を使用して、バージョンのずれを防ぎます。
• ロックファイルを更新する意図がある場合にのみ、apm install --update を実行します。

chezmoi との併用

chezmoi で dotfiles を管理している場合、APM との境界は次のとおりです。

パス	chezmoi	APM
~/.apm/apm.yml	管理（ソースにコピー）	読み取り
~/.apm/apm.lock.yaml	管理（新しいマシンでの再現性のため）	生成
~/.apm/apm_modules/	無視（大きなキャッシュ）	管理
~/.claude/skills/<name>/	無視（APM 管理対象は chezmoi の対象外）	配置先

chezmoi の .chezmoiignore に次を追加します。

.apm/apm_modules
.claude/skills/<apm-managed-name>

自分のスキル（chezmoi add で chezmoi のソースにコピーしたもの）との名前の衝突に注意してください。名前が衝突すると、インストール時に APM が上書きします。詳細は chezmoi-management スキルを参照してください。

リポジトリでのスキル作成

agentskills.io のオープン標準に従ってください。公開に特化したガイド（リポジトリのレイアウト、タグ／リリース、依存関係の宣言、検証チェックリスト）は references/publishing.md にあります。

ディレクトリ構成

my-repo/
└── skills/
    └── my-skill/
        ├── SKILL.md           # Required
        ├── scripts/           # Optional: executable code
        ├── references/        # Optional: detailed docs
        └── assets/            # Optional: templates, resources

SKILL.md の形式

---
name: my-skill
description: One-line description of what this skill does and when to use it.
---

# Skill body

Instructions for the AI agent. Keep under 500 lines.
Move detailed reference material to references/ directory.

フロントマターのフィールド

フィールド	必須	制約
name	はい	1～64 文字、小文字の英数字とハイフンのみ。ディレクトリ名と一致する必要があります
description	はい	1～1024 文字。内容と適用されるタイミングを説明します
license	いいえ	SPDX 識別子またはライセンスファイルへの参照
compatibility	いいえ	環境要件（最大 500 文字）
metadata	いいえ	任意のキーと値のペア

名前の検証ルール

• 小文字、数字、ハイフンのみ使用できます
• ハイフンで始めたり終えたりすることはできません
• ハイフンを連続させることはできません（--）
• 親ディレクトリ名と一致する必要があります

ユーザーによるインストール方法

apm install owner/my-repo/skills/my-skill

ライブラリ作者向けのスキルパターン

ライブラリリポジトリ内の単一スキル

my-library/
├── skills/
│   └── my-library-guide/
│       └── SKILL.md
├── src/
└── package.json

複数のスキル（モノレポ）

my-org-skills/
├── skill-a/
│   └── SKILL.md
├── skill-b/
│   └── SKILL.md
└── skill-c/
    └── SKILL.md

ユーザーは個別にインストールします：apm install owner/my-org-skills/skill-a

ターゲットの検出

APM は、プロジェクト構造から配置先を自動検出します。

ディレクトリの存在	ターゲット	スキルの配置先
.claude/	claude	.claude/skills/
.github/	copilot	.github/skills/
.cursor/	cursor	.cursor/skills/（サポートされている場合）
.codex/	codex	.agents/skills/

APM 0.12 以降では、マーカーとなるディレクトリが存在しない場合に copilot へフォールバックしなくなりました。以前のデフォルトは削除され、apm install は明示的なターゲットを求めてエラーになります。インストールが作業ツリーのディレクトリ構成に依存しないよう、必ず apm.yml に targets: を宣言してください。

name: my-project
version: 1.0.0
targets:
  - claude
dependencies:
  apm:
    - owner/repo

または、コマンドごとに --target claude を指定して上書きできます。

グローバルスコープとプロジェクトスコープ

	プロジェクト（apm install）	グローバル（apm install -g）
マニフェスト	./apm.yml	~/.apm/apm.yml
モジュール	./apm_modules/	~/.apm/apm_modules/
ロックファイル	./apm.lock.yaml	~/.apm/apm.lock.yaml
デプロイ先	./.claude/skills/	~/.claude/skills/
ローカルの .apm/ コンテンツ	デプロイされます	スキップされます

認証

プライベートリポジトリの場合、APM は認証情報を自動的に解決します。

1. gh auth login（GH_TOKEN）— すでにログインしていれば設定不要です
2. git credential fill — OS のキーチェーン、SSH キー
3. GITHUB_APM_PAT 環境変数 — CI または明示的な設定に使用します

gh auth login が実行済みであれば、追加の設定は不要です。

優先順位と競合解決

• 名前が競合した場合、ローカルスキルが依存関係のスキルより常に優先されます
• 依存関係は宣言された順に処理され、最初のものが優先されます
• apm install --force は、競合時にローカルファイルを上書きします