cabinet-fe 构建库技能
为什么
AI 大模型/智能体通常对主流开源库训练充分，使用这些库时准确率高。
但对企业私有库或小众开源项目，AI 大模型/智能体往往无法准确使用。本技能用于指导智能体/AI 为这类库生成高效、准确的文档型技能。
目标
创建专供智能体/AI 使用的库操作手册，帮助其准确、高效地使用该库。
硬约束
- 事实来源：API、签名、约束、示例必须来自公共导出、类型声明、源码、测试、示例、README、CHANGELOG；禁止用训练数据或猜测补齐。
- 仅公共 API：排除
internal、private、未导出、标注@internal/@private的符号。 - 渐进披露：
SKILL.md保持精简；细节放入references/或类似目录，按需加载。 - 技能语言：使用中文撰写；专有名词、API 名称、代码标识符等可保留英文。
- 文档边界：禁止写入库的内部实现细节，只关注公共 API。
目录结构
简单库示例
<skill-name>/
├── SKILL.md
└── references/
├── index.md # 入口：导航与概括说明，并引用 apis.md、examples.md
├── apis.md # API 定义：签名、参数、返回值
└── examples.md # 使用示例
单体仓库示例
<skill-name>/
├── SKILL.md
└── packages/
├── package1/
│ ├── index.md # 入口：导航与概括说明，并引用 apis.md、examples.md
│ ├── apis.md # API 定义：签名、参数、返回值
│ └── examples.md # 使用示例
└── package2/
├── module1/ # 模块分组
│ ├── index.md
│ ├── apis.md
│ └── examples.md
├── module2/
│ ├── index.md
│ ├── apis.md
│ └── examples.md
└── .../
工作流
先确定工作流类型是新增还是更新还是一致性校验, 再按下方对应的工作流执行.
注: 以下提到的向用户确认、提问等操作, 请使用 AskQuestion 或类似的提供选项与自定义输入的工具。
新增
- 分析目标库的源码、测试、文档，确定文档粒度（若库很细，例如「一方法一文件」，则按更粗粒度分类）、触发场景、现有示例，并向用户确认。
- 向用户确认技能名称。
- 以源码、测试为第一优先级，库文档（如有）为补充，规划技能目录结构和其它模糊或有歧义的细节并向用户确认；渐进式披露内容放在
references/（多包单体仓库优先使用packages/）。 - 创建技能目录结构并生成
SKILL.md文件。 - 运行下方的验证流程, 确保技能符合本技能规范。
更新
步骤一：先验证当前技能是否符合本技能规范；若不符合，向用户确认是否重写。
- 若需重写：按「新增」流程执行。
- 若不需重写：进入步骤二。
步骤二：
- 读取目标库的当前版本（
package.json/ 各包package.json/ 发布配置等），与技能SKILL.md中「版本」章节对比。 - 按照库代码更新内容和用户的反馈, 按需更新技能内容。
- 同步更新版本：将
SKILL.md「版本」章节改写为库的当前精确版本；多包仓库须逐包对齐。只要技能内容有变更，版本字段就必须与库当前版本一致，禁止保留旧版本号。 - 运行下方的验证流程, 确保技能符合本技能规范。
一致性校验
- 全量检测源码和技能内容的一致性(使用子代理)，必须包含版本一致性（技能声明版本 vs 库/各包当前版本）。
- 如果一致性通过, 则输出一致性报告, 并告知用户一致性通过。
- 如果一致性不通过, 输出差异报告, 并让用户决策是否更新技能(走更新流程)。
输出落点
除非用户明确指定，否则伴生技能默认放在 skills/ 目录：skills/<skill-name>/。
SKILL.md 模板
元数据字段规范:
name：必须使用kebab-case命名规则; 不超过 32 个字符。description：除专业术语外尽可能使用中文; 不超过 512 个字符; 必须同时包含做什么和何时使用。
---
name: <skill-name>
description: <做什么>以及<何时使用>
---
# <技能名称>
{技能介绍说明}
## 版本
{精确版本, 如果是多包仓库, 则需要说明每个包的版本}
## 模块地图/分包地图
{若库较大或模块较多，在此对各包/模块做粗略介绍，便于初始路由决策}
## 路由决策
{用户意图 → 推荐工作流 / API}
## 检查清单
- 是否已安装
- 安装的依赖版本是否匹配
- ...
自动更新
库代码更新后，伴生技能必须同步更新。
更新清单：
- 公共 API 变更（新增 / 修改 / 删除 / 弃用）已反映到
references/或packages/ - 示例与签名与当前公共 API 一致
- 路由决策、模块地图已按需调整
-
SKILL.md「版本」已更新为库当前精确版本（多包则逐包对齐）
验证
-
SKILL.md足够精简，不得超过 500 行, 200行内最佳 - 检查描述是否具体并包含触发词
- 确保
references/（或packages/）下每个文件都有对应的路由决策路径 - 示例与签名仅使用公共 API，且与当前库版本一致
-
SKILL.md「版本」与库（或各包）当前版本一致 - 测试该 Skill 能否被成功发现并应用
最佳实践
- 示例文档非常重要, 每个示例场景尽可能地以最精简的代码展示出该场景最全面的用法.
- 示例文档尽可能地全面,但是不要每个示例都展示单一的用法.
- 对于 API 说明文件, 类型声明比表格式参数输出更高效, 应该优先使用代码块嵌入类型声明的方式, 例如:
### sum
对任意数字求和.
类型:
```ts
type sum = (...numbers: number[]) => number
```
- SKILL.md 必须在500行内, 200行内最佳.
反模式
- 把整本 API 手册塞进单个
SKILL.md - 为每个导出函数创建独立 Skill
- 无加载条件地罗列
references/（或packages/） - 示例使用内部路径或未导出符号
- 用过时训练知识填写「推荐 API」
- 库代码已变却不更新伴生技能
- 在事实已足够时反复向用户确认琐事