AI Agentic Skills 设计的关键概念

AI Agentic Skills 设计的关键概念 AI Agentic Skills 设计的关键概念 Modified April 13 开发者修改了一个 prompt → Resolver 识别出 “prompt modification” → 加载 docs/EVALS.md → 模型知道在发布前要先运行评估套件 CLAUDE.md 的教训 “我的 CLAUDE.md 曾经有 20,000 行……最后真正的修复只有大约 200 行，就是一堆指向文档的指针。resolver 会在关键时刻加载正确的那个。” 设计启示：不要把所有东西都塞进 system prompt。构建一个能在正确时刻加载正确上下文的 resolver。skills 应该是可发现的，而不是靠死记硬背。 内建 resolver 模式 “每个 skill 都有一个 description 字段，模型会自动把用户意图与 skill descriptions 做匹配。你永远不需要记住 /ship 是否存在。description 就是 resolver。” 6. 三层架构 “Fat skills 在上层……中间是一个 thin CLI harness……底层是你的 application。” Code block Plain Text Copy ┌─────────────────────────────────────────────────────────┐ │ FAT SKILLS │ │ Markdown procedures encoding judgment and process │ │ "90% of the value lives here" │ ├─────────────────────────────────────────────────────────┤ │ THIN HARNESS │ │ 200 lines of code │ │ JSON in, text out, read only by default │ │ Runs model in loop, manages context, enforces safety │ ├─────────────────────────────────────────────────────────┤ │ DETERMINISTIC APPLICATION │ │ QueryDB, ReadDoc, Search, Timeline │ │ Fast, narrow, purpose built tools │ └─────────────────────────────────────────────────────────┘ 反模式 “Fat harness 配上 thin skills。你肯定见过：40 多个 tool definitions 吃掉一半上下文窗口。一个个 god tool 还带着 2 到 5 秒的 MCP 往返延迟。再加上一堆把每个 REST endpoint 都包成单独工具的 API wrappers。” 原则 “把 intelligence 往上推到 skills。把 execution 往下压到 deterministic tooling。让 harness 保持轻薄。” 为什么这很重要 “当你这样做时，模型的每一次进步，都会自动提升每一个 skill，而 deterministic layer 会保持绝对可靠。” 7. 专用定制化工具 “你真正想要的，是 purpose built、快速且窄而专的工具。” 坏： 什么都能做、但做得很慢的通用工具 Chrome MCP：screenshot → find → click → wait → read 时间：每次操作 15 秒 好： 只做一件事、但做得很快的专用工具 Playwright CLI：每次浏览器操作 时间：每次操作 100ms 那就是快 75 倍。 这种心态 “软件已经没必要再那么珍贵了。只构建你真正需要的，而且只构建这些。” 设计启示：不要泛化地包装现成 API。为你的特定工作流构建窄而专的工具。速度会在每次 skill invocation 中复利。 8. 学习循环 能自我改进的 skills 1. Skill 在真实任务上执行 2. 收集反馈（尤其是 “OK” 响应） 3. /improve skill 读取反馈并识别模式 4. 把新规则写回原始 skill 5. 下一次执行就使用改进后的 skill 文章中的例子 输入：12% OK ratings 过程：/improve 对中等质量响应做 diarization，提取模式 输出：把新规则写回 skill： 当参会者说 “AI infrastructure”，但 startup 的 80% 以上代码都在 billing code 上时： → 分类为 FinTech，而不是 AI Infra。 结果： 下一次活动的 OK ratings 下降到 4%。 设计启示：构建能够提出“如何修改自己”的 skills。修改建议应该来自对执行轨迹的检查，而不是对 skill 定义的抽象空想。 9. 技能即永久升级 “你写下的每一个 skill，都是系统的一次永久升级。它不会退化。不会遗忘。它会在你睡觉时，于凌晨 3 点运行。” 指令 “你不被允许做一次性的工作。如果我让你做某件事，而它明显是之后还会再次发生的那类事情，你就必须：第一次先手工做 3 到 10 个样本。把结果给我看。如果我批准了，就把它固化成 skill 文件。如果它应该自动运行，就把它挂到 cron 上。” 测试 “如果我得为同一件事向你提两次要求，那你就失败了。” 设计启示：每一个重复任务都应该变成一个 skill。真正的纪律不在执行，而在 codification。 10. 技能调用模式 同一 skill 结构的多次调用 用于不同目的的同一套结构： MATCHING SKILL（参数化）： /match breakout: 输入：1,200 名 founders 方法：按 sector affinity 聚类 输出：每个房间 30 人，行业同质化 /match lunch: 输入：600 名 founders 方法：Serendipity matching，跨行业混配 输出：每桌 8 人，不重复，LLM 发明主题 /match live: 输入：此刻楼里所有人 方法：Nearest neighbor embedding 输出：1:1 配对，200ms，排除先前见过的人 底层能力相同。 参数化不同。 行为完全不同。 设计启示：把 skills 设计成可配置的，让同一套 procedure 支持多种 use cases。一个参数化 skill 能解决的事情，不要拆成 3 个 skill。 总结：技能设计清单 检查清单 STRUCTURE: □ Skill 有清晰参数（每次 invocation 中什么会变化） □ Skill 编码了 process、judgment 和 constraints（什么是不变的） □ Skill 有 description 字段，供 resolver 匹配 □ 各步骤在 latent 与 deterministic 之间合理交替 BOUNDARIES: □ Judgment 留在 skill 里（latent） □ Execution 外包给窄而专的 tools（deterministic） □ Harness 中不放 business logic □ Tools 要快、而且是 purpose built LIFECYCLE: □ 先手工执行（3 10 个实例） □ 模式稳定后再 codify □ 合适时挂 cron □ 接上自我改进闭环 CONTENT: □ 用 markdown 写（模型原生语言） □ 包含“该如何思考这件事”，而不仅是“做什么” □ 明确写出什么不要做，以及边界情况 □ 记录它优化的目标是什么 INTEGRATION: □ Resolver 能通过 description 找到它 □ 参数有清晰类型/要求 □ 输出格式已指定 □ 在需要的地方能接上 diarization “这才是你获得 Yegge 所说 100x 的方式。不是靠更聪明的模型，而是 fat skills、thin harness，以及把一切都 codify 下来的纪律。” 模型本身已经足够智能。skill 的职责，是给这份 intelligence： • 正确的上下文（通过 resolver） • 正确的流程（通过 skill steps） • 正确的工具（通过 deterministic layer） • 正确的反馈（通过 learning loop） Skills 是 AI 系统中的复利。每一个 skill 都是一次永久升级。真正的纪律，在于把它们建出来。 摘自 Garry Tan 的 “Thin Harness, Fat Skills” 开发者修改了一个 prompt → Resolver 识别出 “prompt modification” → 加载 docs/EVALS.md → 模型知道在发布前要先运行评估套件 CLAUDE.md 的教训 “我的 CLAUDE.md 曾经有 20,000 行……最后真正的修复只有大约 200 行，就是一堆指向文档的指针。resolver 会在关键时刻加载正确的那个。” 设计启示：不要把所有东西都塞进 system prompt。构建一个能在正确时刻加载正确上下文的 resolver。skills 应该是可发现的，而不是靠死记硬背。 内建 resolver 模式 “每个 skill 都有一个 description 字段，模型会自动把用户意图与 skill descriptions 做匹配。你永远不需要记住 /ship 是否存在。description 就是 resolver。” 6. 三层架构 “Fat skills 在上层……中间是一个 thin CLI harness……底层是你的 application。” 反模式 “Fat harness 配上 thin skills。你肯定见过：40 多个 tool definitions 吃掉一半上下文窗口。一个个 god tool 还带着 2 到 5 秒的 MCP 往返延迟。再加上一堆把每个 REST endpoint 都包成单独工具的 API wrappers。” 原则 “把 intelligence 往上推到 skills。把 execution 往下压到 deterministic tooling。让 harness 保持轻薄。” 为什么这很重要 “当你这样做时，模型的每一次进步，都会自动提升每一个 skill，而 deterministic layer 会保持绝对可靠。” 7. 专用定制化工具 “你真正想要的，是 purpose built、快速且窄而专的工具。” 坏： 什么都能做、但做得很慢的通用工具 Chrome MCP：screenshot → find → click → wait → read 时间：每次操作 15 秒 好： 只做一件事、但做得很快的专用工具 Playwright CLI：每次浏览器操作 时间：每次操作 100ms 那就是快 75 倍。 这种心态 “软件已经没必要再那么珍贵了。只构建你真正需要的，而且只构建这些。” 设计启示：不要泛化地包装现成 API。为你的特定工作流构建窄而专的工具。速度会在每次 skill invocation 中复利。 8. 学习循环 能自我改进的 skills 1. Skill 在真实任务上执行 2. 收集反馈（尤其是 “OK” 响应） 3. /improve skill 读取反馈并识别模式 4. 把新规则写回原始 skill 5. 下一次执行就使用改进后的 skill 文章中的例子 输入：12% OK ratings 过程：/improve 对中等质量响应做 diarization，提取模式 输出：把新规则写回 skill： 当参会者说 “AI infrastructure”，但 startup 的 80% 以上代码都在 billing code 上时： → 分类为 FinTech，而不是 AI Infra。 结果： 下一次活动的 OK ratings 下降到 4%。 设计启示：构建能够提出“如何修改自己”的 skills。修改建议应该来自对执行轨迹的检查，而不是对 skill 定义的抽象空想。 9. 技能即永久升级 “你写下的每一个 skill，都是系统的一次永久升级。它不会退化。不会遗忘。它会在你睡觉时，于凌晨 3 点运行。” 指令 “你不被允许做一次性的工作。如果我让你做某件事，而它明显是之后还会再次发生的那类事情，你就必须：第一次先手工做 3 到 10 个样本。把结果给我看。如果我批准了，就把它固化成 skill 文件。如果它应该自动运行，就把它挂到 cron 上。” 测试 “如果我得为同一件事向你提两次要求，那你就失败了。” 设计启示：每一个重复任务都应该变成一个 skill。真正的纪律不在执行，而在 codification。 10. 技能调用模式 同一 skill 结构的多次调用 用于不同目的的同一套结构： MATCHING SKILL（参数化）： /match breakout: 输入：1,200 名 founders 方法：按 sector affinity 聚类 输出：每个房间 30 人，行业同质化 /match lunch: 输入：600 名 founders 方法：Serendipity matching，跨行业混配 输出：每桌 8 人，不重复，LLM 发明主题 /match live: 输入：此刻楼里所有人 方法：Nearest neighbor embedding 输出：1:1 配对，200ms，排除先前见过的人 底层能力相同。 参数化不同。 行为完全不同。 设计启示：把 skills 设计成可配置的，让同一套 procedure 支持多种 use cases。一个参数化 skill 能解决的事情，不要拆成 3 个 skill。 总结：技能设计清单 检查清单 STRUCTURE: □ Skill 有清晰参数（每次 invocation 中什么会变化） □ Skill 编码了 process、judgment 和 constraints（什么是不变的） □ Skill 有 description 字段，供 resolver 匹配 □ 各步骤在 latent 与 deterministic 之间合理交替 BOUNDARIES: □ Judgment 留在 skill 里（latent） □ Execution 外包给窄而专的 tools（deterministic） □ Harness 中不放 business logic □ Tools 要快、而且是 purpose built LIFECYCLE: □ 先手工执行（3 10 个实例） □ 模式稳定后再 codify □ 合适时挂 cron □ 接上自我改进闭环 CONTENT: □ 用 markdown 写（模型原生语言） □ 包含“该如何思考这件事”，而不仅是“做什么” □ 明确写出什么不要做，以及边界情况 □ 记录它优化的目标是什么 INTEGRATION: □ Resolver 能通过 description 找到它 □ 参数有清晰类型/要求 □ 输出格式已指定 □ 在需要的地方能接上 diarization “这才是你获得 Yegge 所说 100x 的方式。不是靠更聪明的模型，而是 fat skills、thin harness，以及把一切都 codify 下来的纪律。” 模型本身已经足够智能。skill 的职责，是给这份 intelligence： • 正确的上下文（通过 resolver） • 正确的流程（通过 skill steps） • 正确的工具（通过 deterministic layer） • 正确的反馈（通过 learning loop） Skills 是 AI 系统中的复利。每一个 skill 都是一次永久升级。真正的纪律，在于把它们建出来。 摘自 Garry Tan 的 “Thin Harness, Fat Skills” 原帖链接：https://x.com/IntuitMachine/status/2043078828583514521 原帖链接：https://x.com/IntuitMachine/status/2043078828583514521 1. 技能是方法调用，而非提示词 基础洞见 “一个 skill 文件的工作方式就像一次方法调用。它接收参数。你用不同的参数去调用它。同样一套流程，会因为你传入的内容不同，而产生完全不同的能力表现。” 二者区别： 提示词 技能 描述一项任务 描述一套流程 单次使用 可重复使用 指明要做什么 指明如何去做 与上下文紧密绑定 参数化、与上下文无关 提示词 提示词 技能 技能 描述一项任务 描述一项任务 描述一套流程 描述一套流程 单次使用 单次使用 可重复使用 可重复使用 指明要做什么 指明要做什么 指明如何去做 指明如何去做 与上下文紧密绑定 与上下文紧密绑定 参数化、与上下文无关 参数化、与上下文无关 文章中的示例： 技能：/调查 参数：目标、问题、数据集 流程：7个步骤（界定范围、确定时间线、分段记录、综合整理、双向论证、引用标注） 调用1：安全科学家+举报人相关问题+取证邮件→医学研究分析师 调用2：空壳公司+捐赠追踪+联邦选举委员会备案文件→法医调查员 同一技能，同一七步流程，应用场景截然不同。 设计启示：将技能编写为带有清晰参数位的流程。技能承载判断逻辑与执行流程，调用时传入具体领域信息。 2. 技能承载的是判断，而非仅仅是步骤 “这不是 prompt engineering。这是软件设计，只不过 markdown 是编程语言，而 human judgment 是运行时。” Skills 里包含什么 • Process：步骤序列 • Judgment：何时做什么、什么更重要、如何权衡 • Context：要高质量执行所需的领域知识 • Constraints：不要做什么、边界情况、失败模式 为什么是 markdown “事实上，Markdown 比刚性源代码更完美地封装了能力，因为它用模型本来就在思考的那种语言，描述了 process、judgment 和 context。” 设计启示：不要把 skills 写成 checklist。要把它们写成关于“如何运用判断力”的指导。模型需要知道的不只是做什么，还包括该如何思考这件事。 3. 潜在性与确定性边界 “你系统中的每一步不是这一类，就是那一类；而把两者混淆，是 agent 设计里最常见的错误。” 潜在空间（由模型来做） • Judgment • Synthesis • Pattern recognition • Interpretation • Quality assessment 确定性的（由代码来做） • Database queries • Arithmetic • File operations • API calls • Combinatorial optimization 餐桌测试 “一个 LLM 可以把 8 个人安排在一张餐桌旁，并兼顾性格与社交动态。但你让它安排 800 个人时，它会编出一个看起来很合理、实际上却完全错误的 seating chart。” 设计启示：skills 应该负责编排这条边界。它们告诉模型该应用什么 judgment，再把执行交给 deterministic tools，然后再回到 judgment 做评估。 Skill 结构 1. LATENT：解释任务，理解需要什么 2. DETERMINISTIC：查询数据、检索文档、计算 3. LATENT：综合结果，施加判断 4. DETERMINISTIC：格式化输出，写文件 5. LATENT：验证质量，决定是否完成 4. Diarization作为核心能力 “Diarization 是让 AI 真正对知识工作变得有用的那一步。模型会读完某个主题上的全部材料，然后写出一份结构化档案，也就是一页纸，凝结了几十份甚至上百份文档中的 judgment。” Diarization 会产出什么 • 从非结构化来源中抽取结构化档案 • 暴露并保留矛盾 • 标出时间上的变化 • Analyst judgment，而不是数据库检索 输出示例 FOUNDER: Maria Santos COMPANY: Contrail SAYS: “Datadog for AI agents” ACTUALLY BUILDING: 80% of commits are in billing module. She’s building a FinOps tool disguised as observability. 为什么它重要 “SQL 查询做不出这个。RAG pipeline 做不出这个。模型必须真的读、在脑中同时保留矛盾、注意到什么变了以及何时变的，并把这些综合成结构化 intelligence。” 设计启示：为你的领域构建 diarization skills。它们能把原始文档转成结构化 intelligence，供其他 skills 消费。 5. 解析器路由上下文 解析器是上下文的路由表。当任务类型X出现时，首先加载文档Y。 解析器的工作方式 检测到任务类型 → 解析器激活 → 相关技能/文档已加载 → 模型继续执行 例子：