apm-usage

APM（Agent Package Manager）

APM 是用于管理 AI Agent 技能、指令、提示词和 MCP 服务的依赖管理器。可以把它看作 Agent 配置领域的 npm。

此技能适用场景

• “为此项目添加一项技能”
• “全局安装技能”
• “为此仓库创建一项技能”
• “设置 apm.yml”
• “更新 Agent 依赖项”

核心命令

# 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 管理点文件，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.

Frontmatter 字段

字段	必填	限制
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

多项技能（monorepo）

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——操作系统钥匙串、SSH 密钥
3. GITHUB_APM_PAT 环境变量——用于 CI 或显式设置

如果已执行 gh auth login，则无需额外配置。

优先级与冲突解决

• 名称冲突时，本地技能始终覆盖依赖项技能
• 按声明顺序处理依赖项；优先采用第一个
• apm install --force 在发生冲突时覆盖本地文件