用了 Hermes 一段时间，我创建了一个又一个 Skill。直到有一天我认真统计了一下：我创建了 18 个 Skill，但实际被自动触发的只有 6 个。剩下的 12 个呢？每次需要用的时候，Hermes 就像完全不认识它们，我只能手动 /skill，像使唤一个记性不好的下属。

按理说，Skill 就是为了解决“让 AI 记住我的偏好和流程”这个问题而设计的。为什么我写了，它却不记？

直到最近研读了《The Complete Guide to Building Skills for Claude》这篇官方指南，才明白问题所在。问题根本不在 Skill 本身，而在我写的那段 frontmatter description。

那段被忽视的描述

很多人写 Skill 的时候，frontmatter 部分都是草草了事：

---
name: my-skill
description: 帮我写周报
---

看起来有在写，对吧？但这种写法等于什么都没写。“帮我写周报”——什么周报？是提取代码提交记录的技术周报，还是汇总本周会议进度的管理周报？Agent 看了这段描述，它的内心独白一定是：“这说了等于没说，我哪儿知道什么时候该用这个技能。”

自然语言路由的本质

读完那篇指南后，我逐渐理解了一个核心概念：frontmatter 的 description，本质上是一次自然语言路由。

指南里其实说得很明白，第一级（YAML frontmatter）始终加载到系统提示中，其唯一目的，就是提供足够的信息让 Agent 知道何时应使用这个 Skill，而无需将所有内容都塞进上下文里。你不是在写文档简介，而是在告诉 Agent 这个 Skill 什么场景下该上场、什么场景下不该上场、它能处理什么、不能处理什么。

一个好的 description 应该包含三件事：它做什么（核心能力）、什么时候用（触发场景）、有什么关键能力（边界说明）。

差的写法	好的写法
帮我写周报	每周五生成工作周报。当用户提到“写周报”、“本周总结”或“汇报进度”时触发。按“核心进展、遗留问题、下周计划”三段式输出，语气需客观简练。

别把说明书全塞给 AI

如果说上面的部分解决了“能不能触发”的问题，那指南里提到的“渐进式披露”（Progressive Disclosure）则解决了“触发之后怎么用”的问题。

很多人以为 Skill 写得越详细越好，把所有流程、注意事项、案例都塞进一个文档。实际上，这种写法往往适得其反——Agent 不是人，它不擅长在一大段文字里抓住重点。指南将 Skills 的知识结构巧妙地分为了三级：

第一级：front matter。一直暴露给 Agent，用来判断是否加载 Skill。这里必须短、准、可触发。
第二级：skill.md 正文。只有当 Agent 判断任务相关时才加载。这里放完整的指令、内核流程和常见错误处理。
第三级：外部资源。比如 references 里的长文档、scripts 里的验证代码、assets 里的模板素材。它们平时不进入上下文，只有被明确需要时才读取或执行。

基于这个原则，skill.md 不要写成大而全的百科。内核指令要清楚可执行——比如不要写“验证数据后再继续”，而要写“运行 validate.py，如果失败检查缺失字段和日期格式”。这个差别就是口号和操作规程的差别。

Skill 不是越大越好，而是越清楚越好。 如果上下文问题明显，就要减少启用数量，或者把相关能力打成 Skill Packs。

要从用例出发

指南里强烈建议，在编写任何指令前，先确定你的 Skill 应该支持的具体用例。很多人做 Skill 正好反过来——先想“我要做一个项目管理 Skill”“我要做一个写作 Skill”，听起来很大，落地时却很虚，因为 Agent 不知道这个 Skill 到底要服务哪个具体任务。

我们可以把用例定义为：Use Case = Trigger + Steps + Result。也就是：场景是什么、用户会怎么触发、需要哪些步骤、最后产出什么结果。

比如“项目 sprint 规划”这个用例：

触发语：帮我规划这个 sprint / 创建 sprint tasks
步骤：获取项目状态 → 分析团队容量 → 建议优先级 → 创建任务并写入标签和估算
结果：一个已经规划好的 sprint，而不是一段泛泛建议

这个结构会逼你把 Skill 写实。你不能只说“帮助项目管理”，你得说当用户提出迭代规划时，Agent 应该拉取哪些信息、如何判断任务优先级、如何处理缺少信息的情况。

常见 Skill 的三种类型

在实际项目中，常见的 Skill 可以分成三类，每一类有不同的侧重点：

1. 文档和资产创建：比如生成报告、PPT、表格、设计稿、代码。这类 Skill 的重点是输出质量，通常会包含分隔指南、母版结构和检查清单。
2. 工作流自动化：适合多步骤流程，重点是步骤验证点和迭代。
3. 工具增强：教 Agent 怎么更好地使用某个外部服务或工具，把原本需要用户解释的操作经验写进 Skill。

如果想做一个 Skill，可以先问自己：我到底在解决哪一种问题？如果三种都想解决，那也可以，但要把边界拆清楚，不要混在一坨指令里。

要用代码检验

很多人对 Skills 的理解停在 Markdown 层面，但指南里反复暗示了一个更高级的方向——不要把所有判断都交给自然语言，能用代码检查的就用代码检验。

Agent 擅长理解意图、擅长生成内容，但它不擅长稳定执行精确检验。比如检查 CSV 字段、验证日期格式这类事，与其依赖 Agent 的“理解能力”，不如写个验证脚本让它执行。

两种常见的失败模式

从指南中，我还了解到两个典型问题，我发现自己两条都占过：

1. Under Triggering（该触发时没触发）：用户不得不手动提醒 Agent“哎，用一下那个 Skill”。这种情况通常是 description 写得太窄，或者触发词没覆盖用户可能的表达方式。
2. Over Triggering（不该触发时乱触发）：一个“高级数据建模”Skill，用户只是想查个简单统计，它就跑出来了。这种情况说明范围写得太泛，需要加上负面触发条件。

写在最后

想明白这件事后，我意识到：Skill Engineering 的第一门课，不是写流程，而是画边界。

一个 Skill 最大的价值，不是它能做什么，而是它不做什么。把边界说清楚了，Agent 才知道什么时候该请它出场，什么时候该换别的技能。这就像一个团队里，每个人的岗位职责要写清楚——不是列出他“能做什么”，而是明确他“只做什么”。

一旦“边界”模糊，那就和某些单位里的糟糕管理者一样。

他们总喜欢把下属当成无所不能的“万金油”，不给资源，只压责任，既没清晰的授权边界，又指望你在所有突发状况下都能完美兜底。一旦出了纰漏，便心安理得地将锅甩给执行层，自己则隐身于“用人失察”的借口之后，摆出一副毫无干系的无辜姿态。蓄意用模糊的边界来掩盖自身的无能，把下属当成挡箭牌，自己却永远立于不败之地。如果这样的管理能成事，那简直荒天下之大缪！

AI Agent也是这样。 你给它清晰的边界，它就给你稳定的输出；你给它模糊的指令，它就给你混乱的结果。

扯远了，回到正题。现在我写 Skill，第一件事不是写 prompt 流程，而是花 5 分钟想清楚：什么样的用户意图，应该触发这个 Skill？把这段 description 写清楚，比写十页使用说明都管用。