新建一个技能文件夹不难。难的是智能体真的会在该用的时候打开它。名称写成 pricing，描述也写成定价相关，会话里客户问围栏报价，技能却一直躺着。作者在写它的那个会话里怎么测都通，换一个全新会话就失灵。问题往往不在步骤写得不够长，而在描述没有承担触发器的职责。

本篇材料来自 Hatched Stacks 视频《How to Write an Agent Skill Your AI Will Use》。数字与主张按视频原话转述。重点放在已经决定写成 Skill 之后，文件内部三层怎么划分才会被调用。不把四件套选型再讲一遍。

图注 左侧为描述、正文、参考的职责对照，右侧为四类种植失败。

一个技能文件里三层各放什么

视频把技能说成含 SKILL.md 的文件夹。文首是名称与短描述，下面是步骤，较长材料放在旁边作参考。智能体只预载名称与描述，匹配到请求才打开正文。因此描述就是触发器。

层级	放什么	不放什么
描述	人在需要这份工作时会说的话，含触发时机	空泛名词、密钥、百科全书
正文步骤	一分钟内能读完的步骤、停顿点、完成标准	长附录、密码、第二件无关工作
旁路参考	只在某步需要时加载的长材料与脚本	每会话必读的事实性记忆

视频还区分了规则、记忆、工具与技能。规则是每会话都带上的短约束。记忆是关于业务的事实。工具让智能体能做事。技能告诉它在已有工具上如何把一件事做对。把事实塞进技能，两处都会过期。把流程塞进规则，一百次用不到报价的会话也要付阅读成本。

描述怎样才像触发器

写成 pricing，智能体不知道何时用。写成当客户问围栏报价时使用，它才知道时机。描述要使用当事人开口时的词，而不是内部系统名。

开放规格给出外沿。名称最长 64 个小写字母、数字或连字符。描述最长 1024 个字符。一项技能只做一件事。描述里若两次用到 and，就该拆开。长材料迁到参考文件，机械步骤变成脚本，保证每次跑法一致。

绝不要写入密码或密钥。写密钥的名字，以及智能体该向何处索取，不要写密钥本身。

离线 smoke 四类种植失败

用模拟团队技能库清单种植四类错，脚本输出见 _w/fail-smoke/skill_trigger.csv。

case	错法	期望
healthy_trigger_desc	描述含时机，一项一事，无密钥，全新会话测过	pass
F1_vague_noun_never_triggers	描述写成空泛名词	fail
F2_two_ands_not_split	描述里 and 两次仍不拆	fail
F3_secret_in_skill_md	密钥写进 SKILL.md	fail
F4_no_fresh_session_claim_ready	未在全新会话测试却宣称可用	fail

F1 导致从不触发。F2 把两件工作捆成一件，匹配与维护都会变差。F3 是安全事故。F4 是假可用。写它的会话已经知道你的意思，证明力很弱。

全新会话的五项检查

视频给出五条。用自己的话问，它会加载。换一种说法问，它仍会加载。问一件相近但不同的事，它保持关闭。走到审批点会停住等待。产出符合完成标准。

五条都过，才能宣称可用。少做相近但不同那条，技能会在隔壁任务里误触发。少做审批停顿，技能会在不该自动继续的地方继续。

当天最小实验

九十分钟。选一件你最常解释的工作，例如围栏报价。

1. 建技能文件夹，名称符合 64 字符规则。
2. 描述写成含触发时机的一句人话，统计 and 次数，大于等于 2 就拆。
3. 正文只留短步骤与停顿点，长价目表放参考。
4. 扫描全文禁止密钥字面量。
5. 打开全新会话，跑五项检查，记 CSV。
6. 种植 F1 到 F4，确认清单能拦住。

验收看描述能否触发、错误描述能否保持关闭、密钥扫描是否为零、全新会话记录是否存在。步骤变长本身不算验收通过。

职责对照与错放后果

错放	后果
描述写成空泛名词	从不打开
把第二件事用 and 塞进同一描述	匹配漂移，难维护
密钥进 SKILL.md	泄露与合规风险
百科留在正文	每回匹配都偏重，该迁参考
只在编写会话测试	F4 假可用
手拷三份到不同智能体目录	副本漂移，修一处漏两处

团队做法是保留一个主文件夹，复制只通过可控同步，不靠手糊。主库进 git，改动可审可回滚。视频提到多种产品能读同一技能格式，但各产品查找目录不同，要以你正在用的为准。

可信来源

视频转述 Anthropic 的提醒。只用自己写的、官方的或经审阅的技能。安装前读每一个文件。即便官方演示库也声明偏演示与教育，依赖前仍要测。他人技能可能带脚本，脚本以智能体当前权限运行，审查不能省。

适用边界

适合已经决定用 Skill 承载单一流程，并需要它在真实会话里被调用的团队。不适合把 Skill 当成存放全部业务事实的记忆库，也不适合把四件套选型问题塞进这篇。失败含义是技能文件存在，但触发、安全或可维护性不成立。

预发口令

第一，描述是否写出触发时机？第二，and 是否少于两次？第三，全文是否无密钥？第四，是否有全新会话五项记录？四句都过，技能才算写到会被调用。

与规则、工具的交接

规则继续放每会话都要遵守的短约束。工具继续通过 MCP 一类通道提供能力。技能只在匹配到工作时打开，教智能体把已有工具按你们办公室的方式用好。交接写进内部手册即可。正文保持零外链。

若你明天只改一件事，先把空泛名词描述改成含时机的人话，并在全新会话里重测加载与关闭。

数字与步骤按视频原话整理。种植 CSV 见 _w/fail-smoke/skill_trigger.csv。本篇不重复四件套往哪放，只处理技能文件内部三层与触发。

写描述的现场做法

先回忆昨晚那次真正做对的报价。客户当时怎么开口。你差点跳过哪一步。那句开口原话写进描述。差点跳过的那一步写进正文停顿点。技能是为真实跑通服务的，不为理想流程海报服务。

描述写完后，找一位没参与编写的同事，用他的口吻提三次请求。一次应触发，换一种说法仍应触发。再问一件相近但不同的事，应保持关闭。三人里若有两人触发失败，先改描述，不先加长正文。

主库与副本

手拷三份到不同产品目录，修一处漏两处，是团队技能库的常见事故。主库只保留一份，复制经同步脚本。同步记录进 git。发现副本内容不一致，以主库为准回滚，不在三个目录里手工挑看起来新的那份。

技能跨产品共用格式，不等于查找路径相同。换产品先确认目录约定，再谈复用。正文零外链，目录约定写在内部手册。

失败注入与回归节奏

每次改描述或拆分技能，先跑种植包再宣布可用。回归最小集就是 healthy 与 F1 到 F4，外加五项全新会话检查记录。缺全新会话记录，视为 F4 未清除。

排障时先问三句。描述是否含触发时机？and 是否少于两次？密钥扫描是否为零？三句不过，先修文件。三句都过仍不触发，再查产品查找目录与预载方式。

若你本周只维护一件技能，先把描述改成人话时机句，并留下全新会话五项记录。