build-lib-skill

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

构建库技能

为什么

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

新增

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

更新

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

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

步骤二：

1. 按照库代码更新内容和用户的反馈, 按需更新技能内容。
2. 运行下方的验证流程, 确保技能符合本技能规范。

一致性校验

1. 全量检测源码和技能内容的一致性(使用子代理)。
2. 如果一致性通过, 则输出一致性报告, 并告知用户一致性通过。
3. 如果一致性不通过, 输出差异报告, 并让用户决策是否更新技能(走更新流程)。

输出落点

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

SKILL.md 模板

元数据字段规范:

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

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

# <技能名称>

{技能介绍说明}

## 版本

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

## 模块地图/分包地图

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

## 路由决策

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

## 检查清单

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

自动更新

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

更新清单：

验证

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

最佳实践

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

### sum

对任意数字求和.

类型:

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

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

反模式

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