distill-to-skill

提炼为技能

将任何知识来源转化为结构良好的 Agent 技能。这是一个流程技能——涵盖如何提取、筛选、重组和编码知识。有关创建技能的机械性工作（目录结构、frontmatter 格式、验证、打包），请使用 skill-creator 技能。

提炼思维

技能不是摘要。它是 Agent 执行任务时使用的决策工具。

提炼时，要不断自问：

• “Agent 执行任务时，知道这点会有所帮助吗？”→ 保留
• “这是背景信息或动机吗？”→ 删除
• “这是否只适用于某种语言或框架，但其中的理念具有普遍性？”→ 转化
• “Agent 能自己弄明白吗？”→ 删除
• “这会改变 Agent 编写代码或做出决策的方式吗？”→ 保留

目标：Agent 加载此技能后，无需阅读原始来源，也能立即写出更好的代码或做出更好的决策。

工作流

第 1 步：吸收来源内容

彻底阅读完整的源材料。对于代码仓库，探索其架构、关键文件和模式。对于文章，从头到尾阅读。不要略读——最有价值的见解往往藏在旁白、脚注和“顺便一提”的段落中。

对于文章／博客文章：

• 获取 URL 并阅读全文
• 记录核心论点（通常为 1–2 句话）
• 找出可执行的规则与解释性文字
• 记录具体的代码示例或模式

对于代码仓库：

• 探索目录结构、入口点和关键模块
• 阅读核心实现文件（而非测试或配置）
• 找出设计模式，而非具体实现
• 记录 TypeScript／类型技巧、架构决策和实用工具模式
• 留意刻意缺少的内容——这往往是最有趣的见解

对于同一主题的多个来源：

• 找出各来源的共同点
• 记录各来源一致之处（高置信度模式）
• 记录各来源存在分歧之处（取决于具体情境的决策）

第 2 步：提取可迁移的核心内容

将精髓与包装区分开来：

保留	删除
通用原则	作者的个人经历
带代码的具体模式	激励性铺垫
决策规则（“出现 X 时，执行 Y”）	关于该领域存在原因的背景介绍
反模式和陷阱	与其他方法的比较
可直接复制粘贴的实用工具	历史背景
检查清单	“延伸阅读”建议

试金石： 如果原始来源不复存在，这项技能本身是否仍然有用？如果有，说明你已正确提取核心内容。

第 3 步：确定技能的形态

单一概念、自成一体 → 仅 SKILL.md（无参考资料）

当一个想法可用约 100–250 行完整表达时使用。这个概念足够连贯，拆分后反而会失去脉络。

今日工作中的示例：

• parse-dont-validate — 一个核心理念（解析优于验证）及实用规则
• karpathy-guidelines — 一组行为规则
• agents-md — 如何编写一种特定文件

宽泛主题、内容深入 → SKILL.md + references/

当主题包含多个不同子主题，且 Agent 可能需要分别使用时采用。SKILL.md 概述原则并提供快速参考；references 则深入介绍各主题。

示例：

• lean-ts-patterns — SKILL.md 中的 7 项原则，以及按领域划分的 5 个参考文件
• agent-first-repo — SKILL.md 中的 3 个支柱，以及分别介绍各支柱的 3 个参考文件

多个互不相关的想法 → 拆分为多个技能

如果来源包含 2 个或更多会在不同情境下触发的概念，请创建单独的技能。它们可以相互交叉引用。

示例：OpenAI 的 harness engineering 文章 → 拆分为 agents-md（如何编写该文件）和 agent-first-repo（更广泛的代码仓库结构），因为它们会在不同情境下触发。

决策启发法：

Does this source contain one core idea?
  YES → Single SKILL.md
  NO → Are the ideas used together?
    YES → SKILL.md + references/
    NO → Separate skills that cross-reference

步骤 4：转换为用户所用的生态系统

源内容可能使用 Haskell、Rust、Go 或纯英文编写。技能应使用 用户偏好的语言和生态系统。

• 代码示例： 改写为目标语言（通常是 TypeScript/Bun）
• 库引用： 映射到目标生态系统中的对应库
• 惯用写法： 使用目标语言的惯用模式（例如，使用品牌类型代替 newtype）
• 确保可运行： 技能中的代码应可直接复制粘贴并正常运行

如果原始见解与语言无关，示例应使用目标语言，但说明文字应保持通用。

步骤 5：组织技能结构

为 SKILL.md 遵循此模板：

---
name: skill-name
description: >-
  [What this enables]. [When to use it — specific scenarios].
  Triggers on: [concrete trigger phrases].
---

# Title

[1-2 line summary. Source attribution if from a specific article/repo.]

## [Core Concept / Principles]

[The distilled rules. Concise. Imperative voice. Code examples inline.]

## [Practical Patterns / Copy-Paste Code]

[Things the agent can use immediately. Concrete, not abstract.]

## [Anti-Patterns / What to Avoid]

[Common mistakes. What NOT to do is often more valuable than what to do.]

## [Checklist / Code Review Guide]

[Verification points. Things to check when reviewing code.]

对于参考文件，每个文件都应：

• 以 1-2 行概述其涵盖的内容
• 内容自成一体，无需阅读 SKILL.md 也能理解
• 提及相关的配套技能名称（不要包含完整内容）
• 控制在约 300 行以内

步骤 6：编写描述（最重要的一行）

YAML description 字段是决定技能是否触发的唯一因素。它会永久加载到上下文中。请谨慎编写：

• 以技能能实现什么开头（而不是它是什么）
• 列出具体场景和文件类型
• 包含用户可能说出的具体触发短语
• 控制在 3-5 行 YAML 以内

不佳："一篇关于类型的博客文章中的模式。" 良好："类型驱动设计：在系统边界将非结构化数据转换为精确类型。适用于编写输入验证、设计数据类型或审查包含冗余空值检查的代码。触发短语：'parse don't validate'、'make illegal states unrepresentable'、'input validation'。"

步骤 7：验证

完成前，请检查：

• Agent 无需阅读原始资料即可使用此技能吗？
• 每个章节都具有可操作性（规则、模式、代码），而非解释性（历史、动机）吗？
• 代码示例使用用户偏好的语言，并且可直接复制粘贴吗？
• SKILL.md 是否少于约 300 行？（如果超出，将详细内容移至 references/）
• 描述中是否包含具体的触发短语？
• 是否包含用于验证的检查清单或代码审查指南？
• 是否按名称引用了配套技能（而非重复其内容）？
• 删除任何章节是否会降低技能的实用性？如果不会，就删掉。

提炼模式

反转

许多文章采用自下而上的讲解方式：问题 → 探索 → 解决方案。 技能应采用自上而下的方式：规则 → 示例 → 反模式。

Agent 不需要被说服，而是需要知道该怎么做。

转换

学术或理论资料通常使用抽象示例。请将其转换为用户领域中具体、真实的场景：

• “NonEmpty 列表” → TypeScript 中的 [T, ...T[]] 元组类型
• “和类型” → 带有 kind 字段的判别联合类型
• “智能构造器” → 带有解析函数的品牌类型
• “Monad” → 异步管道 / Result 类型

压缩

一篇 5,000 字的文章通常可提炼为约 150-250 行的技能。压缩比大致为 10:1 到 20:1。如果技能篇幅快要和源内容一样长，那你做的是总结，而不是提炼。

交叉引用

提炼涉及其他技能已涵盖概念的资料时，不要重复解释，而应引用。用 2-3 句话说明该概念在此处的应用方式，然后指向相关配套技能，供读者深入了解。

Parse data at system boundaries into precise types — don't let raw/untyped data
flow deep into business logic. For the full treatment of branded types, smart
constructors, and the shotgun parsing anti-pattern, see the `parse-dont-validate` skill.

特定来源的提示

博客文章： 通常只有一个核心观点，其中 60% 是动机，30% 是示例，10% 是可执行规则。提取这 10%，并用你自己的示例扩展。

GitHub 仓库： 代码就是内容。重点关注架构模式、值得复用的实用函数、TypeScript 技巧，以及刻意省略的内容。忽略 CI 配置、测试基础设施和构建工具，除非它们正是重点。

文档： 结构通常已经清晰，但内容针对查找优化，而非决策。围绕“何时使用 X”重新组织，而不是“X 的作用是什么”。

论文： 洞见密度高，但往往埋在形式化表述中。提取关键定理或洞见，将其转化为实用的代码模式，并省略证明。

视频转录稿： 内容密度极低。找出讲者提出指导性建议的 2–3 个关键时刻，忽略其余内容。

具体的提炼前后示例，请参阅 references/examples.md。