个人学习小站 SIGNAL DESK 2026
LIVE --:--:--
资讯 人工智能 anthropics/skills 与 agentskills.io 一手直核 + 官方最佳实践 + 掘金 7709761919902482466

Agent Skill 装了不触发?九成卡在 description:SKILL.md 从零避坑与 8 条急救清单

照抄模板装完 Agent Skill 却十次有八次不触发?问题多半不在安装,而在 SKILL.md 的 description。本文按官方规范拆解 name/description 硬约束、触发器四件套写法与三步验证方法,附 8 条翻车急救清单。

2026年11月20日 37 分钟前 作者 站长 约 6 分钟 3 阅读

全网讲 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),理解了这三层,你就明白为什么「不触发」不等于「装坏了」:

Agent Skill 三层渐进式披露示意图

关键在第一层:会话启动时,所有已装 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 坏例与好例对比

两个容易忽略的细节:其一,必须用第三人称——description 会被插入系统提示词,写「我可以帮你…」「你可以用这个来…」这类人称错位会造成路由判断不稳定;其二,负向边界「不用于…」是防乱触发的唯一护栏,尤其当你装了两个功能相近的 Skill 时。另外关键词要塞用户嘴里会说的话:写「处理文档」不如写「提取 PDF 表格、填写表单」,用户怎么描述需求,你就怎么写关键词。

装完别急着用:三句话验证触发

  • 用描述里的关键词原话提一次需求(比如「帮我审查这个接口的鉴权」),看响应是否按 Skill 的步骤走;
  • 换一种不含关键词的问法再试一次,确认它不会误触发;
  • 想点名时敲 /(Claude Code)或 $(Codex)唤起——注意列表里混着 /clear、/compact 这类系统命令,别选错。

常见翻车与急救清单

#症状根因解法
1装了从不触发description 太泛、缺触发词按四件套重写,塞进用户会说的具体词
2该触发的不触发、不该触发的乱触发描述过宽,或多个 Skill 功能重叠加「不用于…」负向边界;下线重叠的 Skill
3name 校验报错大写 / 下划线 / 超 64 字符 / 含预留词改小写连字符,避开 claude、anthropic
4怎么改都不生效name 与文件夹名不一致目录名与 name 字段改成完全一致
5frontmatter 解析失败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 贴在评论区,我帮你看缺了哪一件套。

登录后可点赞、收藏与反馈。

继续阅读 NEXT

更多 →