先说结论
一个 AI Skill 说穿了就是一个文件夹，里面至少有一份 SKILL.md：上半截是 YAML frontmatter（元数据），下半截是给模型看的正文指令。frontmatter 只要 name 和 description 两个字段就合法，但 name 有硬约束（最长 64 字符、只能小写字母数字和连字符、不能头尾是连字符、不能有 --、还必须和父目录同名），description 则直接决定“这个技能什么时候被触发”。这俩写错，要么根本加载不了，要么乱触发、永不触发。
以下数据为 2026-09-26 从 GitHub API 拉取；字段约束以 Agent Skills 开放规范（agentskills.io/specification，最初由 Anthropic 发布）为准。
最小可运行结构
Claude Code 会在 .claude/skills/<技能名>/SKILL.md（项目级）或 ~/.claude/skills/<技能名>/SKILL.md（用户级）下查找技能。一个能用的技能长这样：
my-skill/
└── SKILL.md # 必需：frontmatter + 正文
---
name: my-skill
description: 把 Markdown 表格转成 CSV。当用户提到“表格”“CSV”“导出”或
要处理 Markdown 文档时使用。
---
# Markdown 表格转 CSV
## 步骤
1. 读取用户给的 .md 文件
2. 用脚本 scripts/convert.py 提取表格
3. 输出同名 .csv
## 示例
输入：| a | b |\n|---|---|\n| 1 | 2 |
输出：a,b\n1,2frontmatter 字段清单
对照官方规范，可用字段如下：
| 字段 | 必填 | 约束 |
|---|---|---|
| name | 是 | ≤64 字符；仅小写字母、数字、连字符；不能头尾是连字符；不能含 --；须与目录名一致 |
| description | 是 | ≤1024 字符；非空；写清“做什么 + 何时用” |
| license | 否 | 许可证名或指向附带 LICENSE 文件 |
| compatibility | 否 | ≤500 字符；环境/依赖要求 |
| metadata | 否 | string→string 的键值对 |
| allowed-tools | 否 | 空格分隔的预批准工具，实验性，例：Bash(git:*) Read |
我在 anthropics/skills（178,480 star）里翻了几个真实 SKILL.md，frontmatter 都只有 name / description / license 三行，比如 algorithmic-art 的 description 就是一句话带“Use this when users request…”。
字段里最常被忽略的是 license 和 compatibility。前者给技能标许可证（anthropics/skills 里每个技能都写 license: Complete terms in LICENSE.txt，仓库层面许多技能是 Apache 2.0），公开发布前不标容易踩版权坑；后者只在技能依赖特定运行环境时写，比如“需要 Python 3.14+ 和 uv”，普通技能留空即可，别为了凑字段硬写。
name 的硬规则
最容易踩的就是 name。规范里明确写了：只能小写、数字、连字符，且不能头尾是连字符、不能有连续连字符、必须和目录名一模一样。
# 合法
name: pdf-processing
name: data-analysis
name: code-review
# 非法
name: PDF-Processing # 不允许大写
name: -pdf # 不能以连字符开头
name: pdf--processing # 不能有连续连字符description 怎么写才不漏不滥
这是整篇最关键的部分。description 是模型在“启动时只扫一眼”的摘要，它要判断“这次任务配不配这个技能”。规范给的好/坏样例很说明问题：
“Poor example: description: Helps with PDFs.” —— 太虚，模型不知道什么时候该用。Good example 则写清“Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.”
正反面对比：
| 写法 | 例子 | 后果 |
|---|---|---|
| 太虚 | “处理文档” | 永不触发，等于没装 |
| 关键词堆砌 | “代码、写作、调试、重构、任何任务” | 每次都触发，浪费上下文 |
| 只说做什么 | “格式化 Markdown 表格” | 用户说“导出表格”时模型认不出 |
| 做什么 + 何时用 | “转 CSV。当用户提到表格/CSV/导出时” | 命中率高，且不滥触发 |
看 anthropics/skills 里 academy-guide 的写法最值得抄：它先讲“在什么之前先查我这个技能”，然后直接列 Trigger on: "how do I", "getting started with"...，还补一句“不是用户正干活卡住了要你直接做的时候”。既给了触发词，又划了不触发的边界。
写完别只看字面，要实测触发：开个新会话，用“正常语气”提一句相关任务，看模型有没有自动调用；再故意用无关任务，确认它没误触。两头都要中。触发词太少会“该用时不用”，太多会“每次都跳出来抢戏”，中间那条线只能靠你拿真实对话去调，没有银弹公式。
正文怎么写
- 短、命令式：用“读取…运行…输出…”，别写散文。
- 给示例：输入长什么样、输出长什么样，模型照抄最稳。
- 渐进披露：规范建议主文件控制在 500 行、正文建议 <5000 token；长的参考材料拆到
references/，触发时才读。模型只在激活技能时才加载整份正文，所以把细节外置能省上下文。 - 避坑：正文里别用只有 Claude 懂的私有语法，想跨工具复用就写纯 Markdown。
举个渐进披露的正面样本：技能正文只写“第一步读哪个文件、第二步跑哪个脚本、输出放哪”，真正的字段说明、边界情况挪到 references/REFERENCE.md，并在正文用相对链接指过去。模型只在需要细节时才去读那份参考文件，平时不占上下文。规范还建议主文件压在 500 行、正文建议少于 5000 token——不是硬性上限，而是“别把整本手册一次性灌进去”的经验线。
还有一个可选但好用的字段 allowed-tools：列出这个技能被允许直接调用的工具，省得每次执行都弹确认。规范标注它是实验性的，不同客户端支持度不一，写法如 Bash(git:*) Read。不确定的话先不写，免得在某些工具里直接失效。
# 坏例子：又长又虚，没有触发条件
description: 这个技能很厉害，能帮用户做很多事情，包括各种文件操作。
# 好例子：做什么 + 何时用 + 具体关键词
description: 把 Markdown 表格转成 CSV。当用户提到“表格”“CSV”“导出”，
或要处理 .md 文档中的表格时使用。坑 / 反模式
- name 用了大写或中文，加载直接失败还查不出原因。
- name 和目录名对不上，规范明确要求一致。
- description 只写“做什么”不写“何时用”，触发率全靠运气。
- 把整个手册塞进 SKILL.md 正文，每次触发都灌几千 token。
- 在 description 里堆满关键词想“提高命中”，结果每轮都误触。
怎么验证，下一步怎么做
规范自带校验器，能查 frontmatter 是否合法、命名是否合规：
# 来自 agentskills/agentskills 仓库的 skills-ref
skills-ref validate ./my-skill写完丢进 .claude/skills/ 下，开个新会话让模型碰一下对应任务，看它有没有自动调用。想抄真实样本，直接去 anthropics/skills（178,480 star）翻 skills/ 目录，里面 19 个官方技能都是活的范本。要写文档类技能可顺带看本站的 办公文档专题（docx/xlsx/pptx/pdf）。