深入理解 AI Skill：构造、触发、权限与评估

Skill 是什么：一个文件夹，不是一个提示词

很多人以为 AI Skill 就是一段写得很好的提示词。把它拆开看，最小形态其实是一个文件夹：

competitive-analysis/
├── SKILL.md        # 必有入口：元数据 + 指令
├── scripts/        # 可选：可执行脚本
└── references/     # 可选：参考资源，按需读取

SKILL.md 是唯一必须存在的文件，scripts/ 里放能被 AI 直接调用的脚本，references/ 放需要时才查阅的详细资料。为什么是文件夹而不是单个文件？因为一项"技能"不只是话术，还包括可执行的脚本和可引用的资料——三者放在一起，技能才是自包含的，才能像插件一样被分发、安装、复用。

Skill 由 Anthropic 随 Claude 提出，如今已发展成跨 Agent 的开放规范，ZCode 等各类 Agent 都在用同一套结构。

SKILL.md：两层结构、三个字段

打开 SKILL.md，内部分两层，用三个减号分隔：

---
name: competitive-analysis
description: 当用户需要竞品分析、产品对比时使用；产出覆盖功能、定价、口碑的多维对比报告。
allowed-tools: Read Grep WebSearch
---

## 执行步骤

1. 与用户确认对比对象与维度
2. 检索公开资料，整理成对照表
3. 输出结构化对比报告

上层是 frontmatter（YAML，机器读），管元数据与触发；下层是指令体（Markdown，AI 读），管具体怎么做。一个隐蔽的坑：frontmatter 必须从文件首字节开始，前面哪怕多一个空行，整个文件都无法被识别。

frontmatter 的三个字段各有讲究：

name：唯一标识，受三条硬约束——全小写连字符、不超过 64 字符、必须与父文件夹同名；
description：整个 Skill 的命脉，下文单独展开；
allowed-tools：空格分隔的工具清单，声明这个 Skill 可免确认调用的工具。只写 Read 和 Grep，它就天然是一个只读 Skill。

渐进式披露：装一百个技能也不爆上下文

对 Skill 最普遍的误解是：装上它，就等于把它的全部内容塞进了上下文。真这样，装几十个技能窗口就爆了。

Skill 的解法叫渐进式披露（progressive disclosure）——内容分三个阶段，只在上一层判断"需要"时才加载下一层：

阶段	加载内容	何时发生	上下文成本
一	仅 frontmatter（name + description）	常驻系统提示，用于路由	每个技能仅几十 token
二	完整指令体	description 匹配命中、技能激活时	建议不超过 500 行 / 5000 token
三	references/ 详细文件	指令体引用、真正用到时按需读取	用多少读多少

这套机制解释了两件事。其一，为什么 Skill 能规模化：常驻成本只有一行 description，装一百个技能也不挤压真正干活的空间，新增技能不拖慢旧的。其二，为什么它比把规则全塞进 CLAUDE.md / AGENTS.md 划算：后者每次请求全量携带，前者只在需要时进场。

写 Skill 的对应纪律只有一条：主文件只放高频主流程，长尾细节下沉到 references/。

description：写给路由器，不是写给人

frontmatter 里那一行 description，决定了这个 Skill 的生死。

它的真实身份是路由器：用户每提一个任务，AI 会拿所有已装 Skill 的 description 与任务做语义匹配，命中才激活、才进入上面说的阶段二。所以 description 不是给人看的说明文档——你写"一个有用的分析技能"，它永远匹配不上"帮我对比一下这两家竞品"。

写法公式：触发场景 + 能力产出。前半句写用户会怎么表达（“竞品分析”“产品对比”），给路由提供关键词；后半句写能交付什么（“多维对比报告”），划清能力边界。两半都要具体，都要含用户真实会说的词。

两种典型翻车：

翻车	症状	根因	修复
不触发	装了却从没被调用过	场景模糊、缺关键词、与相邻技能撞车	补全触发场景和用户原话
误触发	不该它管的时候瞎掺和	描述太宽泛（“帮助处理各种任务”）、边界不清	收窄范围、加排他条件

判断一行 description 好不好，最简单的方法是换个视角：假装自己是路由器，拿十条真实用户任务过来，看它能不能对上号。

allowed-tools：权限给多少，看出错代价

allowed-tools 相当于一张预先盖好章的通行证：写进清单的工具，AI 用的时候不再逐次请求确认；没写的走会话默认；整段不写就完全跟随默认。写进去图顺畅，不写图稳妥。

工具按"出错会不会改动东西"分三档：

档位	代表工具	特点
只读	Read、Grep	只看不改，最安全
执行	Bash、WebSearch	会对外做事，中等
写入	Edit、Write	会改文件，最需警惕

核心原则是最小权限：从最安全的往上加，能用只读就别给写入。自检只要一个问题——去掉这个工具，Skill 还能完成任务吗？能就去掉。

更细的尺度看出错代价：动作越危险（删文件、付款、群发），缰绳越紧，少给权限、保留确认；动作越安全（读文件、查资料），越能放手免确认。放权程度与出错代价成反比。最典型的实践是只读 Skill：只给 Read 和 Grep，能查不能改，零误改风险，用户才敢放心让它自动跑。

知 · 触 · 思 · 守：四种外挂的分界线

Skills 常和 MCP、Subagents、Hooks 被搞混。它们其实是给 AI 配的四种"外挂"，各管一件事，一句口诀：知 · 触 · 思 · 守。

机制	口诀	管什么	记忆
Skills	知	可复用的知识、规范、流程，需要时调进对话	与主线共享
MCP	触	把数据库、接口、外部服务变成可调用的工具	与主线共享
Subagents	思	派分身独立干活，干完只带结果回来	自带记忆，可并行
Hooks	守	划红线，强制拦住危险操作	——

最关键的分水岭是记忆共享还是各干各的：Skills 和 MCP 与主线看同一份记忆，信息全程可见但不能同时干活；Subagents 自带记忆、能并行、省上下文，但分身看不到主线全程。要信息互通用前者，要并行省记忆用后者。

真实任务里它们经常一起上：竞品分析，MCP 拉实时数据，Subagents 分头调研各家，Skills 套报告模板，Hooks 守住"只读不改库"。动静互补，各司其职。

eval：Skill 会悄悄失灵

Skill 最大的工程特点：失败是悄无声息的。它不报错、不崩溃，只是该上场时不上场、不该插手时瞎掺和、或者跑到一半因为环境缺依赖而悄悄断掉。这些光读代码看不出来，只有拿真实任务去跑才会暴露。

三种常见的哑巴亏：

不触发：装了却从没被叫到，用户以为没这功能——病根多半在 description 写成了文档；
乱插手：不该它管时瞎掺和，打乱正常任务——描述太宽或与相邻技能边界不清；
掉链子：依赖的脚本、工具在别人电脑上不存在，跑到一半静默失败——开工前没查环境。

解法是一个循环——eval（评估）：拿真实任务跑一遍，看技能有没有按预期被触发、结果对不对；修掉病根；再跑验证，直到稳定。两个要点：一是必须用真实任务测，"理想输入"过关不代表真实场景能过；二是每踩一个坑，就把它变成一道测试用例，以后每次修改自动重跑。没有测试的 Skill 永远在"出了事再补"里打转，有测试的 Skill 把每个坑都变成防线，越改越稳。

写在最后

把六篇的主题收拢成一句话：Skill 是把「会做某件事」从一次性的对话里，沉淀成可分发、可复用、可评估的资产。文件夹让它自包含，frontmatter 三字段让它可路由、可授权，渐进式披露让它可规模化，eval 让它可持续演化。

我自己是这套机制的直接受益者：博客的发布流程、上篇文章介绍的股票回测助手，本质都是 SKILL.md——写一次，到处装，AI 拿着就能干。如果你也在用 AI 助手处理重复性工作，把最常做的那件事写成第一个 Skill，是最好的入门方式。