Skip to content
Hagicode Docs
Blog

skills

1 post with the tag “skills”

为什么使用 Skillsbase 维护自己的 Skills 收藏仓库

为什么使用 Skillsbase 维护自己的 Skills 收藏仓库

Section titled “为什么使用 Skillsbase 维护自己的 Skills 收藏仓库”

说起来也挺好笑的，AI 编程时代来了，我们手里的 Agent Skills 越来越多，可随之而来的麻烦也越来越多。这篇文章就是想聊聊我们是怎么用 skillsbase 解决这些问题的。

背景

Section titled “背景”

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

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

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

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

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

缺乏标准化维护流程

Section titled “缺乏标准化维护流程”
  • 手工复制技能容易出错，难以追踪来源
  • 没有统一的验证机制，无法保证技能仓库的完整性
  • 团队协作时，难以同步和共享技能集合

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

无法满足可复现性要求

Section titled “无法满足可复现性要求”
  • 更换开发机器时，需要重新配置所有技能
  • CI/CD 环境中无法自动验证和同步技能仓库

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

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

其实也是走了不少弯路。

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

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

关于 HagiCode

Section titled “关于 HagiCode”

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

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

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

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

分析

Section titled “分析”

技术挑战

Section titled “技术挑战”

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

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

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

设计权衡

Section titled “设计权衡”

方案一：直接复制目录

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

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

方案二：全局安装后回收

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

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

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

这是 skillsbase 采用的方案：

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

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

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

架构决策

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

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

解决

Section titled “解决”

CLI 架构

Section titled “CLI 架构”

skillsbase CLI 提供四个核心命令：

skillsbase
├── init          # 初始化仓库结构
├── sync          # 同步技能内容
├── add           # 添加新技能
└── github_action # 生成 GitHub Actions 配置

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

核心工作流

Section titled “核心工作流”
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│    init     │───▶│    add      │───▶│    sync     │───▶│github_action│
│  初始化仓库  │    │  添加来源   │    │  同步内容   │    │  生成 CI    │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

一步一步来，急不得。

同步流程设计

Section titled “同步流程设计”
sources.yaml → 解析来源 → npx skills 安装 → 转换结构 → 写入 skills/ → 卸载临时文件
                              ↓
                        .skill-source.json (来源元数据)

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

仓库结构

Section titled “仓库结构”
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

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

实践

Section titled “实践”

初始化技能仓库

Section titled “初始化技能仓库”
Terminal window
# 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>

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

添加技能

Section titled “添加技能”
Terminal window
# 添加单个技能（会自动执行同步）
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

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

同步技能

Section titled “同步技能”
Terminal window
# 执行同步（对账所有来源）
npx skillsbase sync


# 仅检查是否漂移（不修改文件）
npx skillsbase sync --check


# 允许缺失来源（CI 场景）
npx skillsbase sync --allow-missing-sources

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

生成 CI 配置

Section titled “生成 CI 配置”
Terminal window
# 生成 workflow
npx skillsbase github_action --kind workflow


# 生成 action
npx skillsbase github_action --kind action


# 生成全部
npx skillsbase github_action --kind all

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

sources.yaml 配置示例

Section titled “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 元数据示例

Section titled “.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"
}

每个技能目录下都会有这个文件，记录了它的来源信息。这样以后出问题的时候，能快速定位是从哪来的、什么时候同步的。

安全与验证

Section titled “安全与验证”
Terminal window
# 验证仓库结构
node scripts/validate-skills.mjs


# 使用 skills CLI 验证
npx skills add . --list


# 检查更新
npx skills check

验证这东西，说重要也重要，说没必要也没必要。不过为了保险起见，偶尔跑一下也无妨。毕竟，谁知道会不会有什么意外呢？

GitHub Actions 集成

Section titled “GitHub Actions 集成”
.github/workflows/skills-sync.yml
name: Skills Sync


on:
  push:
    paths:
      - 'sources.yaml'
      - 'skills/**'
  workflow_dispatch:


jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Validate repository
        run: |
          npx skills add . --list
          node scripts/validate-skills.mjs
      - name: Sync check
        run: npx skillsbase sync --check

CI 集成之后，每次改 sources.yaml 或者 skills/ 目录，都会自动触发验证。这样就不会出现”本地改了忘了同步”的问题了。

最佳实践

Section titled “最佳实践”
  1. 命名冲突处理：系统技能统一添加 system- 前缀。这样既能保留所有技能，又能避免命名冲突。
  2. 幂等操作：所有命令支持重复执行，多次运行 sync 不会产生副作用。这点在 CI 里特别重要。
  3. 受管文件：生成的文件包含 # Managed by skillsbase CLI 注释，方便识别和管理。这些文件可以安全覆盖，手工修改不会被保留。
  4. 非交互模式：CI 环境默认使用确定性行为，不会因为交互式提示而中断。所有配置都通过 sources.yaml 声明。
  5. 来源可追溯：每个技能都有 .skill-source.json 记录来源信息，出问题的时候能快速定位。

团队协作

Section titled “团队协作”
Terminal window
# 团队成员安装共享技能库
npx skills add your-org/myskills -g --all


# 本地克隆验证
git clone https://github.com/your-org/myskills.git
cd myskills
npx skills add . --list

通过 Git 管理技能仓库，团队成员可以轻松同步技能集合，确保每个人都使用相同版本的工具和配置。

这点在团队协作里特别有用，不会出现”我这边能跑你那边不行”的情况。毕竟，环境统一了，问题就少了一半。

总结

Section titled “总结”

使用 skillsbase 维护技能收藏仓库的核心价值在于：

  • 安全性：来源验证、冲突检测、受管文件保护
  • 可维护性：统一入口、幂等操作、配置即文档
  • 标准化：统一的目录结构、命名规范、元数据格式
  • 自动化：CI/CD 集成、自动同步、自动验证

通过这套方案，开发者可以像管理 npm 包一样管理自己的 Agent Skills，实现可复现、可共享、可维护的技能仓库体系。

本文分享的这套工具和流程，正是我们在开发 HagiCode 过程中实际踩坑、实际优化出来的方案。如果你觉得这套方案有价值，说明我们的工程实践方向是正确的——那么 HagiCode 本身也值得关注一下。

毕竟，好的工具是值得被更多人使用的。

参考资料

Section titled “参考资料”

如果本文对你有帮助：

本文首发于 HagiCode 博客

版权说明

Section titled “版权说明”

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。 本内容采用人工智能辅助协作,最终内容由作者审核并确认。