# Build Lib Skill

> 为库、SDK 或 package 创建或更新伴生 Agent Skill。目标仓库安装本技能后，将其视为库项目； 在库代码更新、用户提出创建/更新技能时使用。

- Skill: `cabinet-fe/build-lib-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cabinet-fe/build-lib-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cabinet-fe/build-lib-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cabinet-fe (https://skillmd.com/u/cabinet-fe)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cabinet-fe/build-lib-skill

---


# 构建库技能

## 为什么

AI 大模型/智能体通常对主流开源库训练充分，使用这些库时准确率高。

但对企业私有库或小众开源项目，AI 大模型/智能体往往无法准确使用。本技能用于指导智能体/AI 为这类库生成高效、准确的**文档型**技能。

## 目标

创建**专供智能体/AI 使用**的库操作手册，帮助其准确、高效地使用该库。

## 硬约束

- **事实来源**：API、签名、约束、示例必须来自公共导出、类型声明、源码、测试、示例、README、CHANGELOG；禁止用训练数据或猜测补齐。
- **仅公共 API**：排除 `internal`、`private`、未导出、标注 `@internal` / `@private` 的符号。
- **渐进披露**：`SKILL.md` 保持精简；细节放入 `references/` 或类似目录，按需加载。
- **技能语言**：使用中文撰写；专有名词、API 名称、代码标识符等可保留英文。
- **文档边界**：禁止写入库的内部实现细节，只关注公共 API。

## 目录结构

### 简单库示例

```text
<skill-name>/
├── SKILL.md
└── references/
    ├── index.md      # 入口：导航与概括说明，并引用 apis.md、examples.md
    ├── apis.md       # API 定义：签名、参数、返回值
    └── examples.md   # 使用示例
```

### 单体仓库示例

```text
<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` 或类似的提供选项与自定义输入的工具。

### 新增

1. 分析目标库的源码、测试、文档，确定文档粒度（若库很细，例如「一方法一文件」，则按更粗粒度分类）、触发场景、现有示例，并向用户确认。
2. 向用户确认技能名称。
3. 以源码、测试为第一优先级，库文档（如有）为补充，规划技能目录结构和其它模糊或有歧义的细节并向用户确认；渐进式披露内容放在 `references/`（多包单体仓库优先使用 `packages/`）。
4. 创建技能目录结构并生成 `SKILL.md` 文件。
5. 运行下方的验证流程, 确保技能符合本技能规范。

### 更新

**步骤一**：先验证当前技能是否符合本技能规范；若不符合，向用户确认是否重写。

- 若需重写：按「新增」流程执行。
- 若不需重写：进入步骤二。

**步骤二**：

1. 读取目标库的当前版本（`package.json` / 各包 `package.json` / 发布配置等），与技能 `SKILL.md` 中「版本」章节对比。
2. 按照库代码更新内容和用户的反馈, 按需更新技能内容。
3. **同步更新版本**：将 `SKILL.md`「版本」章节改写为库的当前精确版本；多包仓库须逐包对齐。只要技能内容有变更，版本字段就必须与库当前版本一致，禁止保留旧版本号。
4. 运行下方的验证流程, 确保技能符合本技能规范。

### 一致性校验

1. 全量检测源码和技能内容的一致性(使用子代理)，**必须包含版本一致性**（技能声明版本 vs 库/各包当前版本）。
2. 如果一致性通过, 则输出一致性报告, 并告知用户一致性通过。
3. 如果一致性不通过, 输出差异报告, 并让用户决策是否更新技能(走更新流程)。

## 输出落点

除非用户明确指定，否则伴生技能默认放在 `skills/` 目录：`skills/<skill-name>/`。

## SKILL.md 模板

元数据字段规范:

- `name`：必须使用 `kebab-case` 命名规则; 不超过 32 个字符。
- `description`：除专业术语外尽可能使用中文; 不超过 512 个字符; 必须同时包含`做什么`和`何时使用`。

```markdown
---
name: <skill-name>
description: <做什么>以及<何时使用>
---

# <技能名称>

{技能介绍说明}

## 版本

{精确版本, 如果是多包仓库, 则需要说明每个包的版本}

## 模块地图/分包地图

{若库较大或模块较多，在此对各包/模块做粗略介绍，便于初始路由决策}

## 路由决策

{用户意图 → 推荐工作流 / API}

## 检查清单

- 是否已安装
- 安装的依赖版本是否匹配
- ...
```

## 自动更新

库代码更新后，伴生技能必须同步更新。

更新清单：

- [ ] 公共 API 变更（新增 / 修改 / 删除 / 弃用）已反映到 `references/` 或 `packages/`
- [ ] 示例与签名与当前公共 API 一致
- [ ] 路由决策、模块地图已按需调整
- [ ] **`SKILL.md`「版本」已更新为库当前精确版本**（多包则逐包对齐）

## 验证

- [ ] `SKILL.md` 足够精简，不得超过 500 行, 200行内最佳
- [ ] 检查描述是否具体并包含触发词
- [ ] 确保 `references/`（或 `packages/`）下每个文件都有对应的路由决策路径
- [ ] 示例与签名仅使用公共 API，且与当前库版本一致
- [ ] **`SKILL.md`「版本」与库（或各包）当前版本一致**
- [ ] 测试该 Skill 能否被成功发现并应用

## 最佳实践

- 示例文档非常重要, 每个示例场景尽可能地以最精简的代码展示出该场景最全面的用法.
- 示例文档尽可能地全面,但是不要每个示例都展示单一的用法.
- 对于 API 说明文件, 类型声明比表格式参数输出更高效, 应该优先使用代码块嵌入类型声明的方式, 例如:

````md
### sum

对任意数字求和.

类型:

```ts
type sum = (...numbers: number[]) => number
```
````

- SKILL.md 必须在500行内, 200行内最佳.

## 反模式

- 把整本 API 手册塞进单个 `SKILL.md`
- 为每个导出函数创建独立 Skill
- 无加载条件地罗列 `references/`（或 `packages/`）
- 示例使用内部路径或未导出符号
- 用过时训练知识填写「推荐 API」
- 库代码已变却不更新伴生技能
- 在事实已足够时反复向用户确认琐事