agent-skill-manager (asm) 详细部署教程

项目概述

agent-skill-manager（简称 asm）是一个专为 AI 编程代理设计的通用技能管理器。它是一个可脚本化的 CLI 工具，支持跨 21 种 AI 编程工具（如 Claude Code、Codex、Cursor 等）安装、搜索、审计和组织技能。

核心特性：

跨 21 个提供商管理技能，统一视图
支持 --json 和 --yes 标志，适合非交互式自动化使用
安装前进行安全扫描
提供可选的 TUI 界面用于本地浏览
MIT 许可证，无账户要求，无遥测

部署前准备

系统要求

项目	要求
操作系统	Windows / macOS / Linux
Node.js	22+（安装脚本要求 18.0.0+）
npm	9.0.0+
终端	支持 ANSI 颜色的终端

检查环境

在开始之前，请确认你的系统已安装 Node.js 和 npm：

1 2	node --version npm --version

如果未安装，请从 nodejs.org 下载安装。

方案一：npm 全局安装（推荐）

这是最简单、最标准的部署方式。

步骤 1：全局安装 asm

1	npm install -g agent-skill-manager

npm 会同时安装两个命令别名：asm 和 agent-skill-manager 。

步骤 2：验证安装

1	asm --version

如果输出显示版本号，说明安装成功。如果出现关于多个 asm 二进制文件的警告，运行 asm doctor 进行诊断。

步骤 3：查看已安装的技能

1	asm list --json

这会返回所有已发现技能的 JSON 格式列表。

步骤 4：安装一个技能

1	asm install github:anthropics/skills --yes

方案二：使用安装脚本（一键安装）

如果你希望自动化整个安装过程，可以使用官方提供的安装脚本。

步骤 1：安全审查脚本（推荐）

在运行任何远程脚本之前，建议先审查其内容：

1 2	curl -sSL https://raw.githubusercontent.com/luongnv89/asm/main/install.sh -o install.sh less install.sh

步骤 2：运行安装脚本

1	bash install.sh

该脚本会自动执行以下操作：

检测操作系统（Linux、macOS、Windows/WSL）和架构
检查 Node.js >= 18.0.0 和 npm >= 9.0.0
通过 npm install -g 全局安装 agent-skill-manager
验证安装（检查 asm 和 agent-skill-manager 命令是否可用）
如果 PATH 中存在旧的 asm 二进制文件，会发出警告

步骤 3：验证安装

1	asm --version

方案三：从源码构建

如果你需要最新开发版本或希望参与贡献，可以从源码构建。

步骤 1：克隆仓库

1 2	git clone https://github.com/luongnv89/asm.git cd asm

步骤 2：安装依赖并构建

1 2	npm install npm run build

步骤 3：运行

npm start

或者直接运行构建后的 CLI：

1	node dist/cli.js --help

首次配置

配置文件位置

首次运行时，asm 会在 ~/.config/agent-skill-manager/config.json 创建默认配置文件。

查看配置

1	asm config show

编辑配置

1	asm config edit

配置示例

{
  "version": 1,
  "providers": [
    {
      "name": "claude",
      "label": "Claude Code",
      "global": "~/.claude/skills",
      "project": ".claude/skills",
      "enabled": true
    },
    {
      "name": "codex",
      "label": "Codex",
      "global": "~/.codex/skills",
      "project": ".codex/skills",
      "enabled": true
    }
  ],
  "customPaths": [],
  "preferences": {
    "defaultScope": "both",
    "defaultSort": "name"
  }
}

配置说明 ：

所有 21 个提供商默认启用
设置 "enabled": false 可禁用不需要的提供商
通过 customPaths 添加自定义目录
使用 asm config show|path|reset|edit 管理配置

常用命令

技能管理

任务	命令
列出所有技能	`asm list --json`
搜索技能	`asm search "code review" --json`
安装技能	`asm install code-review -p claude --yes --json`
卸载技能	`asm uninstall old-skill --yes`
检查技能详情	`asm inspect my-skill --json`

审计与统计

任务	命令
移除重复技能	`asm audit --yes`
查找功能重叠	`asm audit overlap`
查看上下文成本	`asm stats --tokens`
安全审计	`asm audit security github:user/repo`
常驻审计	`asm audit residency`

技能开发

任务	命令
创建新技能	`asm init my-skill -p claude`
实时开发链接	`asm link ./my-skill -p claude`
发布到注册表	`asm publish ./my-skill --yes`
评估质量	`asm eval ./my-skill`

使用 TUI 界面

如果你偏好图形界面而非命令行，可以运行 TUI（终端用户界面）。

启动 TUI

asm

（不带任何参数即可启动）

键盘快捷键

按键	功能
`↑/↓` 或 `j/k`	导航列表
`Enter`	查看详情
`d`	卸载
`/`	搜索/过滤
`Esc`	返回/清除
`Tab`	切换范围
`s`	切换排序
`r`	刷新
`c`	配置
`a`	审计重复
`q`	退出
`?`	帮助

高级用法

1. 参考层级：使用技能而不安装

asm get <skill> 可以将技能内容输出到 stdout，而不会安装它：

# 输出技能正文
asm get code-review

# 保存但不安装
asm get code-review > /tmp/SKILL.md

# 借用完整技能目录
borrowed_path="$(asm get --path code-review)"
# 使用后清理
asm cleanup "$borrowed_path"

2. 即时可选依赖

技能可以声明可选依赖，而不安装它们：

1
2
3

asm deps discover parent-skill --json
asm deps acquire code-review --session run-123 --json
asm deps release --session run-123 --json

3. 从私有仓库安装

1	asm install github:user/private-skill --transport ssh --yes

4. 安装技能包

1 2	asm bundle install frontend-dev --yes asm bundle install devops --yes

常见问题排查

问题	症状	解决方案
命令未找到	`asm: command not found`	确保 npm 全局 bin 目录在 PATH 中，运行 `npm prefix -g` 查看路径
多个二进制文件冲突	版本不匹配警告	运行 `asm doctor` 诊断，移除旧版本
权限错误	EACCES 错误	使用 `sudo` 或配置 npm 全局目录权限
技能未显示	`asm list` 为空	检查提供商是否启用，运行 `asm config show`
安装失败	网络超时	检查网络连接，确保 `git` 已安装并在 PATH 中

诊断命令

1	asm doctor

这会运行环境健康检查并报告潜在问题。

支持的 AI 工具

asm 支持 21 个内置提供商，全部默认启用：

工具	全局路径	项目路径
Agents	`~/.agents/skills/`	`.agents/skills/`
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Codex	`~/.codex/skills/`	`.codex/skills/`
Cursor	`~/.cursor/rules/`	`.cursor/rules/`
GitHub Copilot	`~/.github/instructions/`	`.github/instructions/`
Gemini CLI	`~/.gemini/skills/`	`.gemini/skills/`
Windsurf	`~/.windsurf/rules/`	`.windsurf/rules/`
…	…	…

完整列表请参考 asm config show。

总结

部署方式	适用场景	难度	推荐度
npm 全局安装	大多数用户	⭐	⭐⭐⭐⭐⭐
安装脚本	快速自动化部署	⭐	⭐⭐⭐⭐
从源码构建	开发或最新功能	⭐⭐⭐	⭐⭐⭐