| 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 或类似的提供选项与自定义输入的工具。
新增
- 分析目标库的源码、测试、文档,确定文档粒度(若库很细,例如「一方法一文件」,则按更粗粒度分类)、触发场景、现有示例,并向用户确认。
- 向用户确认技能名称。
- 以源码、测试为第一优先级,库文档(如有)为补充,规划技能目录结构和其它模糊或有歧义的细节并向用户确认;渐进式披露内容放在
references/(多包单体仓库优先使用 packages/)。
- 创建技能目录结构并生成
SKILL.md 文件。
- 运行下方的验证流程, 确保技能符合本技能规范。
更新
步骤一:先验证当前技能是否符合本技能规范;若不符合,向用户确认是否重写。
- 若需重写:按「新增」流程执行。
- 若不需重写:进入步骤二。
步骤二:
- 按照库代码更新内容和用户的反馈, 按需更新技能内容。
- 运行下方的验证流程, 确保技能符合本技能规范。
一致性校验
- 全量检测源码和技能内容的一致性(使用子代理)。
- 如果一致性通过, 则输出一致性报告, 并告知用户一致性通过。
- 如果一致性不通过, 输出差异报告, 并让用户决策是否更新技能(走更新流程)。
输出落点
除非用户明确指定,否则伴生技能默认放在 skills/ 目录:skills/<skill-name>/。
SKILL.md 模板
元数据字段规范:
name:必须使用 kebab-case 命名规则; 不超过 32 个字符。
description:除专业术语外尽可能使用中文; 不超过 512 个字符; 必须同时包含做什么和何时使用。
---
name: <skill-name>
description: <做什么>以及<何时使用>
---
# <技能名称>
{技能介绍说明}
## 版本
{精确版本, 如果是多包仓库, 则需要说明每个包的版本}
## 模块地图/分包地图
{若库较大或模块较多,在此对各包/模块做粗略介绍,便于初始路由决策}
## 路由决策
{用户意图 → 推荐工作流 / API}
## 检查清单
- 是否已安装
- 安装的依赖版本是否匹配
- ...
自动更新
库代码更新后,伴生技能必须同步更新。
更新清单:
验证
最佳实践
- 示例文档非常重要, 每个示例场景尽可能地以最精简的代码展示出该场景最全面的用法.
- 示例文档尽可能地全面,但是不要每个示例都展示单一的用法.
- 对于 API 说明文件, 类型声明比表格式参数输出更高效, 应该优先使用代码块嵌入类型声明的方式, 例如:
### sum
对任意数字求和.
类型:
```ts
type sum = (...numbers: number[]) => number
```
- SKILL.md 必须在500行内, 200行内最佳.
反模式
- 把整本 API 手册塞进单个
SKILL.md
- 为每个导出函数创建独立 Skill
- 无加载条件地罗列
references/(或 packages/)
- 示例使用内部路径或未导出符号
- 用过时训练知识填写「推荐 API」
- 库代码已变却不更新伴生技能
- 在事实已足够时反复向用户确认琐事