其实也不能说是什么大问题只是东西多了管理起来就麻烦了。技能分散存储管理成本高本地技能散落在多个位置~/.agents/skills/、~/.claude/skills/、~/.codex/skills/.system/等不同位置可能存在命名冲突例如skill-creator同时存在于用户目录和系统目录缺乏统一的管理入口备份和迁移困难这点挺烦人的。有时候你自己都不知道某个技能到底在哪像丢了东西一样找起来费劲。缺乏标准化维护流程手工复制技能容易出错难以追踪来源没有统一的验证机制无法保证技能仓库的完整性团队协作时难以同步和共享技能集合手工操作嘛总是容易出错的。毕竟人的记忆力有限谁记得住那么多东西是从哪来的呢无法满足可复现性要求更换开发机器时需要重新配置所有技能CI/CD 环境中无法自动验证和同步技能仓库换个电脑就得重新来一遍这种感觉怎么说呢就像搬家一样麻烦。每次都得重新适应新的环境重新配置所有东西。为了解决这些痛点我们尝试过多种方案从手工复制到脚本自动化从直接管理目录到全局安装再回收。每种方案都有各自的缺陷要么无法保证一致性要么污染环境要么难以在 CI 中使用。其实也是走了不少弯路。最终我们找到了一套更优雅的解决方案——skillsbase。这个方案的核心思想是先本地安装验证再转换结构写入仓库最后卸载临时文件。这样既能确保仓库内容与实际安装结果一致又不会污染全局环境。说起来简单只是踩了不少坑才琢磨出来罢了。关于 HagiCode本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 代码助手项目在开发过程中我们需要维护大量的 Agent Skills 来扩展各种编码能力。正是这些实际需求促使我们开发了 skillsbase 这套工具来规范化管理技能仓库。其实这东西也不是凭空想出来的都是被逼的。技能多了自然就需要管理。管理的过程中遇到问题自然就需要解决。一步一步就走到今天了。如果你对 HagiCode 感兴趣可以访问 官网了解更多 或在 GitHub 上查看源码。分析技术挑战要建立一个可维护的技能收藏仓库需要解决以下核心问题统一命名空间冲突当多个来源存在同名技能时如何避免覆盖来源可追溯性如何记录每个技能的来源以便后续更新和审计同步与验证如何确保仓库内容与实际安装结果一致自动化集成如何与 CI/CD 流程集成实现自动同步和验证这些问题看似简单但每一个都够头疼的。不过话说回来做什么事不难呢设计权衡方案一直接复制目录优点实现简单缺点无法保证与skillsCLI 实际安装结果一致这个方案嘛说真的我们也想过。只是后来发现CLI 安装的时候可能有一些预处理逻辑直接复制就跳过了。结果就是复制的东西和实际装的东西不一样这就有问题了。方案二全局安装后回收优点可以验证安装过程缺点污染执行环境CI 与本地结果难以保持一致这个方案更糟糕。全局安装会污染环境。更麻烦的是CI 环境和本地环境很难保持一致导致本地能跑CI 失败的问题。这种感觉谁懂啊方案三本地安装 → 转换 → 卸载最终方案这是 skillsbase 采用的方案先通过npx skills把技能安装到临时位置转换目录结构并添加来源元数据写入目标仓库最后卸载临时文件这种方案确保了仓库内容与实际消费者安装结果一致同时不污染全局环境转换过程可标准化支持幂等操作。其实这个方案也不是一开始就想到的只是试错试多了自然就知道什么可行、什么不可行了。架构决策决策项选择理由运行时Node.js ESM无需构建步骤.mjs足以完成文件系统编排配置格式YAML (sources.yaml)可读性强支持人工维护命名策略命名空间前缀用户技能保持原名系统技能添加system-前缀工作流add修改清单 →sync执行同步单一同步引擎避免规则双份实现文件管理受管文件标识添加注释头支持安全覆盖这些决策说到底都是为了一个目标让事情变得简单。毕竟简单才是王道。解决CLI 架构skillsbaseCLI 提供四个核心命令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/myskillsgit 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 配置# 生成 workflownpx skillsbase github_action --kind workflow# 生成 actionnpx skillsbase github_action --kind action# 生成全部npx skillsbase github_action --kind allCI 配置也是自动生成的。只是你需要自己调整一些细节比如触发条件、运行环境之类的。不过这些都不难。sources.yaml 配置示例# 技能根目录配置skillsRoot: skills/metadataFile: .skill-source.json# 来源定义sources:# 第一方本地用户技能first-party:type: localpath: /home/user/.agents/skillsnaming: original # 保持原名includes:- documentation-writer- frontend-design- skill-creator# 系统系统提供技能system:type: localpath: /home/user/.codex/skills/.systemnaming: prefix-system # 添加 system- 前缀includes:- imagegen- openai-docs- skill-creator # 会变成 system-skill-creator# 远程第三方仓库vercel:type: remoteurl: vercel-labs/agent-skillsnaming: originalincludes:- 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}每个技能目录下都会有这个文件记录了它的来源信息。这样以后出问题的时候能快速定位是从哪来的、什么时候同步的。安全与验证# 验证仓库结构node scripts/validate-skills.mjs# 使用 skills CLI 验证npx skills add . --list# 检查更新npx skills check验证这东西说重要也重要说没必要也没必要。不过为了保险起见偶尔跑一下也无妨。毕竟谁知道会不会有什么意外呢GitHub Actions 集成# .github/workflows/skills-sync.ymlname: Skills Syncon:push:paths:- sources.yaml- skills/**workflow_dispatch:jobs:validate:runs-on: ubuntu-lateststeps:- uses: actions/checkoutv4- uses: actions/setup-nodev4with:node-version: 20- name: Validate repositoryrun: |npx skills add . --listnode scripts/validate-skills.mjs- name: Sync checkrun: npx skillsbase sync --checkCI 集成之后每次改sources.yaml或者skills/目录都会自动触发验证。这样就不会出现本地改了忘了同步的问题了。最佳实践命名冲突处理系统技能统一添加system-前缀。这样既能保留所有技能又能避免命名冲突。幂等操作所有命令支持重复执行多次运行sync不会产生副作用。这点在 CI 里特别重要。受管文件生成的文件包含# Managed by skillsbase CLI注释方便识别和管理。这些文件可以安全覆盖手工修改不会被保留。非交互模式CI 环境默认使用确定性行为不会因为交互式提示而中断。所有配置都通过sources.yaml声明。来源可追溯每个技能都有.skill-source.json记录来源信息出问题的时候能快速定位。团队协作# 团队成员安装共享技能库npx skills add your-org/myskills -g --all# 本地克隆验证git clone https://github.com/your-org/myskills.gitcd myskillsnpx skills add . --list通过 Git 管理技能仓库团队成员可以轻松同步技能集合确保每个人都使用相同版本的工具和配置。这点在团队协作里特别有用不会出现我这边能跑你那边不行的情况。毕竟环境统一了问题就少了一半。总结使用skillsbase维护技能收藏仓库的核心价值在于安全性来源验证、冲突检测、受管文件保护可维护性统一入口、幂等操作、配置即文档标准化统一的目录结构、命名规范、元数据格式自动化CI/CD 集成、自动同步、自动验证通过这套方案开发者可以像管理 npm 包一样管理自己的 Agent Skills实现可复现、可共享、可维护的技能仓库体系。本文分享的这套工具和流程正是我们在开发 HagiCode 过程中实际踩坑、实际优化出来的方案。如果你觉得这套方案有价值说明我们的工程实践方向是正确的——那么 HagiCode 本身也值得关注一下。毕竟好的工具是值得被更多人使用的。