Agent Skill 装了不触发?九成卡在 description:SKILL.md 从零避坑与 8 条急救清单
照抄模板装完 Agent Skill 却十次有八次不触发?问题多半不在安装,而在 SKILL.md 的 description。本文按官方规范拆解 name/description 硬约束、触发器四件套写法与三步验证方法,附 8 条翻车急救清单。
全网讲 Agent Skills 的教程,九成九都在讲同一件事:「Skill 就是一个文件夹」。但几乎没人告诉你,照着模板把文件夹放进 skills 目录之后,最常见的结局是——你在对话框里认真提了十次需求,Agent 有八次当它不存在。你以为是自己装坏了,删掉重装、换了三个教程,问题依旧。
真相是:Skill 能不能被用起来,八成不取决于安装,而取决于 SKILL.md 顶部那行 description——它是模型决定「这次要不要用你」的唯一依据。本文按 Anthropic 官方规范(anthropics/skills 仓库与 agentskills.io 开放标准)逐条拆硬约束,带你从零写一个能在 Claude Code、Codex、Cursor 等 46+ 兼容客户端通用的 Skill,不会写正式代码也能跟着做完。
先交个底:按这套规范写一个接口审查类 Skill,常驻上下文开销只有百 token 量级;不触发、乱触发、校验报错这三类最常见的坑,文末的 8 条急救清单对着查就行。
先搞懂触发机制:Agent 凭什么决定用不用你的 Skill?
Skill 采用三层渐进式披露(progressive disclosure),理解了这三层,你就明白为什么「不触发」不等于「装坏了」:

关键在第一层:会话启动时,所有已装 Skill 的 name 和 description 常驻上下文,每个约百 token 量级,装 20 个也只占一两千 token——这是它比把所有规则塞进全局规则文件省得多的原因(全局规则文件的取舍,参考之前写过的 AGENTS.md 三层知识库)。但代价是:模型对你的全部认知,就只有这两行元数据。需求进来时,它拿用户的话去匹配每条 description,匹配不上,你的 Skill 就沉底,正文永远不会被读。
所以「装了从不触发」的准确解释是:description 里没有用户会说的那些词。解法是改描述,不是重装。
全局规则、快捷提示词、Skill,先分清再动手
动手之前先确认你真的需要 Skill,三者各归其位:
| 承载方式 | 上下文开销 | 适合放什么 | 典型例子 |
|---|---|---|---|
| 全局规则(AGENTS.md / CLAUDE.md) | 每次对话完整读取 | 每次干活都必须遵守的基础约定 | 「本项目 Vue3 + Vite,构建跑 npm run build」 |
| 快捷提示词(Prompt) | 用时粘贴,不常驻 | 一两句话的日常叮嘱 | 「先定位问题用直白话讲,先别改代码」 |
| Skill | 仅 name + description 常驻 | 有判断标准或多步脚本的专项能力 | 审查接口、生成周报、批量改文件名的工作流 |
一句话判断:一两句话说不清、要带步骤或脚本的,才值得做成 Skill。把九九乘法表做成 Skill 并不会让模型数学变好——太通用的 Skill 只会白占目录层。
手写 SKILL.md:四条硬约束,别让校验直接拦你
SKILL.md = YAML frontmatter + Markdown 正文,最小可用结构如下:
my-review-skill/
├── SKILL.md # 必需:元数据 + 指令
├── scripts/ # 可选:固化脚本
├── references/ # 可选:长文档 / 检查清单
└── assets/ # 可选:模板、静态资源
以下数字全部来自官方规范,踩一次就白装一轮:
- name:≤64 字符,只能用小写字母、数字、连字符,且必须与文件夹同名;官方还禁用 claude / anthropic 等预留词——官方仓库里就有一个技能因名字带 claude 被专门提交改名的记录。
- description:非空、≤1024 字符、不含 XML 标签。1024 不是拍脑袋:官方仓库的 academy-guide 技能曾因描述写到 1176 字符超过上传校验上限,被压缩到 992 字符才通过。
- 正文建议控制在 500 行以内,长内容拆进 references/,文件引用保持一层深。
- 路径一律用正斜杠——Windows 用户注意,反斜杠是官方最佳实践里点名的坑。
frontmatter 本体其实只有两行:
---
name: my-review-skill
description: 审查 REST 接口的鉴权、参数校验与错误处理。当用户要求检查或编写 API 路由时使用;不用于纯前端页面。
---
## 执行步骤
1. 先读 references/checklist.md,按 P0/P1/P2 分级
2. 每项结论附 file:line 引用
3. 全部确认后输出审查报告
三种安装姿势:手动、命令行、让 Agent 自己装
Skill 装的就是个文件夹,放到 Agent 会读的目录即可:全局放 ~/.claude/skills/(Codex 是 ~/.codex/skills/),项目内放 .claude/skills/ 或 .agents/skills/ 随仓库共享。三种装法:
- 手动:GitHub 下载压缩包,解压进对应目录,最直观;
- 命令行:装了 Node.js 的话跑
npx skills add 用户名/仓库名,按提示勾选装到哪个 Agent; - 让 Agent 自己装(最推荐):把仓库地址发给它,说一句「帮我从这个地址下载 Skill,装到对应目录,再检查是否能读取」——它最清楚自己的目录在哪。
关键一步:把 description 写成「触发器」
官方最佳实践对描述的要求,可以浓缩成四件套:第三人称、做什么、什么时候用、不用于什么。

两个容易忽略的细节:其一,必须用第三人称——description 会被插入系统提示词,写「我可以帮你…」「你可以用这个来…」这类人称错位会造成路由判断不稳定;其二,负向边界「不用于…」是防乱触发的唯一护栏,尤其当你装了两个功能相近的 Skill 时。另外关键词要塞用户嘴里会说的话:写「处理文档」不如写「提取 PDF 表格、填写表单」,用户怎么描述需求,你就怎么写关键词。
装完别急着用:三句话验证触发
- 用描述里的关键词原话提一次需求(比如「帮我审查这个接口的鉴权」),看响应是否按 Skill 的步骤走;
- 换一种不含关键词的问法再试一次,确认它不会误触发;
- 想点名时敲
/(Claude Code)或$(Codex)唤起——注意列表里混着/clear、/compact这类系统命令,别选错。
常见翻车与急救清单
| # | 症状 | 根因 | 解法 |
|---|---|---|---|
| 1 | 装了从不触发 | description 太泛、缺触发词 | 按四件套重写,塞进用户会说的具体词 |
| 2 | 该触发的不触发、不该触发的乱触发 | 描述过宽,或多个 Skill 功能重叠 | 加「不用于…」负向边界;下线重叠的 Skill |
| 3 | name 校验报错 | 大写 / 下划线 / 超 64 字符 / 含预留词 | 改小写连字符,避开 claude、anthropic |
| 4 | 怎么改都不生效 | name 与文件夹名不一致 | 目录名与 name 字段改成完全一致 |
| 5 | frontmatter 解析失败 | YAML 格式错(冒号后没空格、描述含冒号) | description 整行用引号包起来再写 |
| 6 | 装了几十个后 Agent 反而变笨 | 所有 description 常驻上下文,互相干扰路由 | 精简到真正常用的几个(与 MCP 工具裁剪同一逻辑) |
| 7 | 触发后效果变差 | 正文超 500 行挤占注意力 | 细节拆 references/,正文只留步骤与判断标准 |
| 8 | 脚本不跑、工具找不到 | 依赖没写安装命令、MCP 工具没写全限定名 | 指令里显式写 pip install;工具写成 Server:tool 形式 |
边界与实话:什么时候别用 Skill
- Skill 是「教」不是「强制」:它只影响模型决策,不保证执行到位。需要 100% 执行的硬校验(提交前必跑 lint 之类),请上 hook 或 CI,别指望 Skill。
- 没遇到真问题别预装:官方与社区口径一致——遇到重复痛点再引入。聚合站一口气装几十个,是新手翻车重灾区。
- 跨端兼容有细节差异:agentskills.io 标准已有 46+ 客户端宣布兼容(Codex、Cursor、Gemini CLI、GitHub Copilot 等),但目录位置、唤起符号各端不同,迁移时以各端文档为准。
这套规范最大的好处,是把「AI 使用姿势」从聊天记录里解放出来变成可分发的文件。你写的第一个 Skill 卡在哪一步?是不触发、乱触发还是校验报错?把你的 description 贴在评论区,我帮你看缺了哪一件套。
登录后可点赞、收藏与反馈。