在 AI 编程时代，开发者需要维护越来越多的 Agent Skills——这些是可复用的指令集，用于扩展 Claude Code、OpenCode、Cursor 等编码助手的能力。然而，随着技能数量的增长，一个现实问题逐渐浮现：

其实也不能说是什么大问题，只是东西多了，管理起来就麻烦了。

技能分散存储，管理成本高

• 本地技能散落在多个位置：~/.agents/skills/、~/.claude/skills/、~/.codex/skills/.system/ 等
• 不同位置可能存在命名冲突（例如 skill-creator 同时存在于用户目录和系统目录）
• 缺乏统一的管理入口，备份和迁移困难

这点挺烦人的。有时候你自己都不知道某个技能到底在哪，像丢了东西一样，找起来费劲。

缺乏标准化维护流程

• 手工复制技能容易出错，难以追踪来源
• 没有统一的验证机制，无法保证技能仓库的完整性
• 团队协作时，难以同步和共享技能集合

手工操作嘛，总是容易出错的。毕竟人的记忆力有限，谁记得住那么多东西是从哪来的呢？

无法满足可复现性要求

• 更换开发机器时，需要重新配置所有技能
• CI/CD 环境中无法自动验证和同步技能仓库

换个电脑就得重新来一遍，这种感觉，怎么说呢，就像搬家一样麻烦。每次都得重新适应新的环境，重新配置所有东西。

为了解决这些痛点，我们尝试过多种方案：从手工复制到脚本自动化，从直接管理目录到全局安装再回收。每种方案都有各自的缺陷，要么无法保证一致性，要么污染环境，要么难以在 CI 中使用。

其实也是走了不少弯路。

最终，我们找到了一套更优雅的解决方案——skillsbase。这个方案的核心思想是：先本地安装验证，再转换结构写入仓库，最后卸载临时文件。这样既能确保仓库内容与实际安装结果一致，又不会污染全局环境。

说起来简单，只是踩了不少坑才琢磨出来罢了。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。

HagiCode 是一个 AI 代码助手项目，在开发过程中我们需要维护大量的 Agent Skills 来扩展各种编码能力。正是这些实际需求，促使我们开发了 skillsbase 这套工具来规范化管理技能仓库。

其实这东西也不是凭空想出来的，都是被逼的。技能多了，自然就需要管理。管理的过程中遇到问题，自然就需要解决。一步一步，就走到今天了。

如果你对 HagiCode 感兴趣，可以访问 官网了解更多 或在 GitHub 上查看源码。

分析

技术挑战

要建立一个可维护的技能收藏仓库，需要解决以下核心问题：

1. 统一命名空间冲突：当多个来源存在同名技能时，如何避免覆盖？
2. 来源可追溯性：如何记录每个技能的来源，以便后续更新和审计？
3. 同步与验证：如何确保仓库内容与实际安装结果一致？
4. 自动化集成：如何与 CI/CD 流程集成，实现自动同步和验证？

这些问题看似简单，但每一个都够头疼的。不过话说回来，做什么事不难呢？

设计权衡

方案一：直接复制目录

优点：实现简单
缺点：无法保证与 skills CLI 实际安装结果一致

这个方案嘛，说真的，我们也想过。只是后来发现，CLI 安装的时候可能有一些预处理逻辑，直接复制就跳过了。结果就是，复制的东西和实际装的东西不一样，这就有问题了。

方案二：全局安装后回收

优点：可以验证安装过程
缺点：污染执行环境，CI 与本地结果难以保持一致

这个方案更糟糕。全局安装，会污染环境。更麻烦的是，CI 环境和本地环境很难保持一致，导致"本地能跑，CI 失败"的问题。这种感觉，谁懂啊？

方案三：本地安装 → 转换 → 卸载（最终方案）

这是 skillsbase 采用的方案：

• 先通过 npx skills 把技能安装到临时位置
• 转换目录结构并添加来源元数据
• 写入目标仓库
• 最后卸载临时文件

这种方案确保了仓库内容与实际消费者安装结果一致，同时不污染全局环境，转换过程可标准化，支持幂等操作。

其实这个方案也不是一开始就想到的，只是试错试多了，自然就知道什么可行、什么不可行了。

架构决策

决策项	选择	理由
运行时	Node.js ESM	无需构建步骤，.mjs 足以完成文件系统编排
配置格式	YAML (sources.yaml)	可读性强，支持人工维护
命名策略	命名空间前缀	用户技能保持原名，系统技能添加 system- 前缀
工作流	add 修改清单 → sync 执行同步	单一同步引擎，避免规则双份实现
文件管理	受管文件标识	添加注释头，支持安全覆盖

这些决策，说到底都是为了一个目标：让事情变得简单。毕竟，简单才是王道。

解决

CLI 架构

skillsbase CLI 提供四个核心命令：

skillsbase

├── init # 初始化仓库结构

├── sync # 同步技能内容

├── add # 添加新技能

└── github_action # 生成 GitHub Actions 配置

命令不多，但也够了。毕竟，工具这东西，够用就好。

核心工作流

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐

│ init │───▶│ add │───▶│ sync │───▶│github_action│

│ 初始化仓库 │ │ 添加来源 │ │ 同步内容 │ │ 生成 CI │

└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘

一步一步来，急不得。

同步流程设计

sources.yaml → 解析来源 → npx skills 安装 → 转换结构 → 写入 skills/ → 卸载临时文件

↓

.skill-source.json (来源元数据)

这个流程设计得还算清晰。至少我自己看的时候，能明白每一步在做什么。

仓库结构

repos/skillsbase/

├── sources.yaml # 来源清单（单一真相源）

├── skills/ # 技能目录

│ ├── frontend-design/ # 用户技能

│ ├── skill-creator/ # 用户技能

│ └── system-skill-creator/ # 系统技能（带前缀）

├── scripts/

│ ├── sync-skills.mjs # 同步脚本

│ └── validate-skills.mjs # 验证脚本

├── docs/

│ └── maintainer-workflow.md # 维护者文档

└── .github/

├── workflows/

│ └── skills-sync.yml # CI 工作流

└── actions/

└── skillsbase-sync/

└── action.yml # 复用型 Action

文件多了点，不过也还好。毕竟，组织结构清晰了，维护起来也方便。

实践

初始化技能仓库

# 1. 创建空仓库

mkdir repos/myskills && cd repos/myskills

git init

# 2. 使用 skillsbase 初始化

npx skillsbase init

# 输出：

# [1/4] create manifest ................. done

# [2/4] create scripts .................. done

# [3/4] create docs ..................... done

# [4/4] create github workflow .......... done

#

# next: skillsbase add <skill-name>

这一步会生成一堆文件，不过不用担心，都是自动生成的。接下来就可以开始添加技能了。

添加技能

# 添加单个技能（会自动执行同步）

npx skillsbase add frontend-design --source vercel-labs/agent-skills

# 添加到本地来源

npx skillsbase add documentation-writer --source /home/user/.agents/skills

# 输出：

# source: first-party ......... updated

# target: skills/frontend-design ... synced

# status: 1 skill added, 0 removed

添加技能挺简单的，一条命令就够了。只是有时候会遇到一些意外情况，比如网络不好、权限问题之类的。不过这些都是小事，慢慢来。

同步技能

# 执行同步（对账所有来源）

npx skillsbase sync

# 仅检查是否漂移（不修改文件）

npx skillsbase sync --check

# 允许缺失来源（CI 场景）

npx skillsbase sync --allow-missing-sources

同步的时候，系统会把 sources.yaml 里定义的来源都检查一遍，然后和 skills/ 目录里的内容对账。有差异就更新，没差异就跳过。这样就不会出现"配置改了但文件没变"的问题。

生成 CI 配置

# 生成 workflow

npx skillsbase github_action --kind workflow

# 生成 action

npx skillsbase github_action --kind action

# 生成全部

npx skillsbase github_action --kind all

CI 配置也是自动生成的。只是你需要自己调整一些细节，比如触发条件、运行环境之类的。不过这些都不难。

sources.yaml 配置示例

# 技能根目录配置

skillsRoot: skills/

metadataFile: .skill-source.json

# 来源定义

sources:

# 第一方：本地用户技能

first-party:

type: local

path: /home/user/.agents/skills

naming: original # 保持原名

includes:

- documentation-writer

- frontend-design

- skill-creator

# 系统：系统提供技能

system:

type: local

path: /home/user/.codex/skills/.system

naming: prefix-system # 添加 system- 前缀

includes:

- imagegen

- openai-docs

- skill-creator # 会变成 system-skill-creator

# 远程：第三方仓库

vercel:

type: remote

url: vercel-labs/agent-skills

naming: original

includes:

- web-design-guidelines

这个配置文件是整个系统的核心。所有的来源都在这里定义，改了这里，下次同步就会生效。所以说，这算是一个"单一真相源"。

.skill-source.json 元数据示例

{

"source": "first-party",

"originalPath": "/home/user/.agents/skills/documentation-writer",

"originalName": "documentation-writer",

"targetName": "documentation-writer",

"syncedAt": "2026-04-07T00:00:00.000Z",

"version": "unknown"

}

每个技能目录下都会有这个文件，记录了它的来源信息。这样以后出问题的时候，能快速