library-reference-distillation

库参考提炼——原型手册

提炼本仓库中已发布的库参考提炼所共有的约定——这种原型会将一个外部库转化为符合惯用法的规则集。它不是生成器，而是一组约束，用于指导 /dev-skill:new 无法替你做出的编辑决策。

这是位于 /dev-skill:new 和 /dev-skill:ingest 之上的原型层。生成器负责搭建结构框架。此技能负责你为每个库参考技能反复做出的四项决策：从哪里获取资料、如何防止版本漂移、如何设计分类与规则，以及如何让元数据成为可信的校验和。

何时使用

在以下情况下使用此技能：

• 开始新的库参考提炼（该库有文档，且其稳定接口值得提炼为惯用法规则）
• 针对上游新版本或主要版本升级，更新现有库参考技能
• 审查一份看起来“像是把文档改写了一遍”的库参考技能草稿
• 为新技能选择分类与前缀方案，但觉得这些选择很随意
• 决定是否要在 SKILL.md 标题中固定上游版本，还是只在 metadata.json 中固定
• 更新某个技能，而你怀疑其中的规则已偏离上游（openai-codex-rust-patterns 的经验表明：不同快照之间的 codex-rs 变化很大）

此技能不适用于：

• 代码图谱提炼（例如 openai-codex-rust-patterns、opencode-ts、nextjs-ppr-patterns）——资料来源是固定在某个 HEAD 的真实代码仓库，而不是上游文档。相应的原型手册尚待提炼。
• 方法论提炼（例如 radical-simplification、deterministic-metric-design）——资料来源是具名人物及其经典著作，而不是某个库。
• 脚手架工具（例如 expo-design-system-scaffolder）——关注的是组合工作流，而不是规则手册。

使用方法

这四个类别代表你为每项技能各做一次、彼此独立的决策。根据症状选择对应做法：

症状	选择	首先阅读的规则
不知道从哪里挖掘规则	来源	source-priority-ladder
规则像是在复述 API，而非承载关键知识	来源（缺口分析）	source-failure-gap
库变化很快，技能会过时	版本固定	pin-by-velocity
现有技能正逐渐偏离上游	版本固定（刷新）	pin-refresh-vs-head
分类显得随意	设计	shape-category-ladder
“何时使用”无法可靠触发	设计（何时使用）	shape-when-to-apply-template
引用列表与规则来源已不一致	元数据	meta-references-checksum

关于分类概览和排序依据，请参阅 references/_sections.md。

规则类别

#	类别	前缀	做法	规则数
1	来源选择	source	从哪里挖掘；什么样的规则具有关键价值	2
2	版本管理	pin	如何根据 API 变化速度固定版本；如何刷新	2
3	规则设计	shape	通用的四层阶梯；“何时使用”模板	2
4	元数据规范	meta	将 references[] 作为真实可信的引用集校验和	1

快速参考

1. 来源选择

• source-priority-ladder — 文档 → 博客/变更日志 → GitHub 讨论 → 类型定义 → 示例；只有当库发布了 llms.txt（Effect）时，才会颠倒这一优先顺序
• source-failure-gap — 优先选择能捕捉文档遗漏、并经生产实践验证的规则；如果某条规则只是在复述 API，就删掉

2. 版本管理

• pin-by-velocity — 稳定的 API（Zod、RHF）→ 版本仅保存在 metadata.json 中；快速变化的 API（nuqs v2.5–v2.8、Tailwind v4）→ 在 SKILL.md 标题中明确标注版本范围
• pin-refresh-vs-head — 演进时，将技能与上游 HEAD 进行差异对比；将版本差异带来的经验教训固化为规则（codex-rs 从 codex.rs 拆分为 session/ 是典型示例）

3. 规则形态

• shape-category-ladder — 每个已发布的 library-ref 技能都按层级排列：CRITICAL 配置 → HIGH 隔离性／性能 → MEDIUM 组合／集成 → LOW 边缘情况／润色；选择与此对应的类别名称，不要另创一种形态
• shape-when-to-apply-template — 4 个要素：导入语句触发条件 + 问题领域表述 + 使用频率信号 + 明确指出不要执行哪些操作的边界，并指向相关的同类技能

4. 元数据规范

• meta-references-checksum — metadata.references[] 必须与规则中引用的 URL 集合完全一致，不能多也不能少；若两者不一致，说明规则或元数据有一方不实

相关技能

• radical-simplification — 本技能之上的思考层；本手册本身就是将“简化 → 约束 → 命名不变量”这一系列做法应用于技能编写的实例
• skill-authoring — 跨类型的技能编写约定；本技能是针对库参考的特化版本
• deterministic-metric-design — 方法论提炼方面的同类技能；展示了相同的类型模式如何应用于另一种类型（证明按类型编写手册的思路具有普适性）

编写说明

这些规则是承重结构，不是装饰。它们通过追溯 5 个已发布的 library-ref 技能（nuqs、zod、react-hook-form、effect-ts、emilkowal-animations）中规则引用来源的方式提炼而来。每条规则都指出，缺少这些约定时，作者容易采用哪种错误的默认做法。如果某条规则重述了 /dev-skill:new 已经处理的内容，就删掉它。覆盖情况由 /dev-skill:eval 在真实的库知识提炼提示词上进行验证，而不是靠规则数量证明。提取下一个类型手册（code-atlas、methodology、scaffolder、runbook）时，这里反复出现的模式可考虑提升为通用的 skill-authoring 技能；有所不同的模式则继续保留为特定类型的约定。