axn-skills

SKILL 平台的 AI Agent Skill 管理 CLI 工具。

简介

axn-skills 是一个命令行工具，用于从Skill 平台注册中心发现、安装和管理 AI Agent 技能。支持多种 AI 编码助手（Claude Code、Cursor、Codex、Qoder、Trae、CodeBuddy），并将技能安装到各 Agent 的原生技能目录中。

安装

# 通过 npm 全局安装
npm install -g axn-skills

# 或通过 npx 直接使用（无需预装）
npx axn-skills <命令>

要求 Node.js >= 18。

命令

axn-skills add <skill>

从注册中心安装技能到项目中的 Agent 技能目录。

# 交互模式 — 会提示选择目标 Agent
npx axn-skills add openspec-to-superpowers

# 直接模式 — 指定 Agent，跳过交互选择
npx axn-skills add openspec-to-superpowers --agent claude-code

执行流程：

1. 验证技能是否存在于注册中心（先按 name 匹配，未找到则按 sourceRepo 匹配）
2. 检测项目中有哪些 AI Agent 目录（.claude、.cursor 等）
3. 交互选择目标 Agent（已检测到的会自动勾选）
4. 从注册中心下载技能 zip 包，解压后复制到各 Agent 技能目录
5. 向注册中心上报安装事件（用于统计分析）
6. 清理临时文件

各 Agent 安装目录：

| Agent | 技能目录 | |-------------|-------------------------------| | Claude Code | .claude/skills/<skill-name> | | Cursor | .cursor/skills/<skill-name> | | Codex | .codex/skills/<skill-name> | | Qoder | .qoder/skills/<skill-name> | | Trae | .trae/skills/<skill-name> | | CodeBuddy | .codebuddy/skills/<skill-name>|

axn-skills find [query]

搜索注册中心中的技能。

# 按关键词搜索
npx axn-skills find vue

# 列出所有热门技能
npx axn-skills find

输出包含技能名称、描述、安装次数和审核状态的表格。

axn-skills check

列出本地已安装的技能（检测所有已识别的 Agent）。

# 检查所有已检测到的 Agent
npx axn-skills check

# 仅检查指定 Agent
npx axn-skills check --agent claude-code

axn-skills update <skill>

重新下载并重新安装技能（强制更新，不做版本比较）。

# 交互模式
npx axn-skills update openspec-to-superpowers

# 直接模式
npx axn-skills update openspec-to-superpowers --agent claude-code

axn-skills init [name]

在当前目录或指定子目录中初始化 SKILL.md 模板。

# 在当前目录创建模板
npx axn-skills init

# 创建指定名称的子目录和模板
npx axn-skills init my-skill

axn-skills publish

发布技能到注册中心。当前为引导入口，引导至 Web 发布页面：

npx axn-skills publish
# 输出：请使用 Web 发布页面发布技能。Visit: https://skillplatform.aisino.com/publish

axn-skills config

管理 CLI 配置。

# 设置注册中心 URL（用于私有/自定义注册中心）
axn-skills config --registry http://localhost:8080/aisino-skills

# 设置认证令牌
axn-skills config --token <your-token>

# 显示当前配置
axn-skills config --list

配置文件存储在 ~/.axn-skills/config.json。

默认配置：

| 配置项 | 默认值 | |---------------|------------------------------------------| | registryUrl | http://localhost:8080/aisino-skills | | defaultAgent| claude-code | | verbose | false |

配置说明

如果未执行 axn-skills config --registry <url>，CLI 默认使用 http://localhost:8080/aisino-skills。配置文件 ~/.axn-skills/config.json 在首次修改配置时自动创建。

Skill 名称解析

使用 add <skill> 安装技能时，CLI 按两个优先级解析技能名称：

1. 按 name 匹配 — 匹配 skill_info 表的 name 字段
2. 按 sourceRepo 匹配（兜底） — 若 name 未匹配到，则匹配 source_repo 字段

例如，执行 npx axn-skills add openspec-to-superpowers 时，先查找 name 为 openspec-to-superpowers 的技能。若未找到，则按 sourceRepo 搜索。如果 sourceRepo 匹配到的技能 name 不同，CLI 会使用解析后的名称进行下载和安装。

项目架构

src/
├── cli.ts                         # 入口文件，注册所有命令
├── commands/
│   ├── add.ts                     # 安装技能（验证 → 下载 → 安装 → 上报）
│   ├── find.ts                    # 搜索/列出注册中心技能
│   ├── check.ts                   # 列出本地已安装技能
│   ├── update.ts                  # 重新下载并安装技能
│   ├── init.ts                    # 创建 SKILL.md 模板
│   ├── config.ts                  # 管理 CLI 配置（注册中心、令牌）
│   └── publish.ts                 # 引导入口 — 跳转 Web 发布页面
├── services/
│   ├── registry.ts                # 注册中心 API 调用（列表、详情、搜索、下载、上报）
│   ├── download.ts                # 下载 zip + 解压（去除仓库根目录前缀）
│   ├── install.ts                 # 将解压内容复制到 Agent 技能目录
│   ├── agent-discovery.ts         # 检测已安装的 Agent + 交互选择
│   ├── config.ts                  # 加载/保存配置（~/.axn-skills/config.json）
│   └── report.ts                  # 上报安装事件（非阻塞）
├── utils/
│   ├── output.ts                  # 彩色输出（chalk）+ 进度提示（ora）
│   └── path.ts                    # Agent 技能目录路径映射
├── constants.ts                   # 默认注册中心 URL、配置路径、默认值
└── types.ts                       # TypeScript 接口与枚举定义

核心依赖

| 包名 | 用途 | |------------|------------------------| | commander| CLI 框架 | | axios | 注册中心 HTTP 客户端 | | adm-zip | Zip 包解压 | | inquirer | 交互式 Agent 选择 | | ora | 终端进度提示 | | chalk | 终端彩色输出 |

构建

使用 tsup 打包为 CJS + ESM 双格式，附带 TypeScript 类型声明。

npm run build    # 构建 dist/
npm run dev      # 开发模式（watch）

测试

使用 vitest，node 环境。

npm test         # 运行所有测试

发布到 npm

使用 npm publish 发布到 npmjs：

npm publish --provenance --access public

工作流（publish.yml）执行：npm ci → npm run build → npm test → npm publish --provenance --access public。

需要在 GitHub 仓库设置中配置 NPM_TOKEN 密钥。

更新 CLI

axn-skills 本身也需要定期更新以获取新功能。update 命令仅更新已安装的 skill，不会更新 CLI 工具自身。

全局安装方式

# 查看当前版本
axn-skills --version

# 更新到最新版
npm update -g axn-skills

npx 方式

npx 默认使用本地缓存，可能不会自动拉取最新版。更新方法：

# 方式一：清除 npm 缓存后重新使用（推荐）
npm cache clean --force
npx axn-skills@latest <command>

# 方式二：每次明确指定 latest 版本
npx axn-skills@latest add openspec-to-superpowers

# 方式三：查看当前使用的版本
npx axn-skills@latest --version

提示：如果之前用 npx 运行过旧版本，npx 会缓存该版本直到缓存过期或被手动清除。遇到异常行为时，先尝试 npm cache clean --force。

许可证

MIT