大多数每天使用 Claude、ChatGPT 或 Cursor 的人，从未写过一个 Agent Skill，并且理所当然地认为那需要写代码。事实并非如此。Agent Skill 就是一个 Markdown 文件。如果你能为新同事写一份像样的交接文档，你今天下午就能写出第一个 Skill。
这件事之所以重要，是因为 Skill 解决了进阶 AI 使用者最恼人的问题：每开一个新对话，就要重新粘贴一次设定指令。品牌语调规则、报告格式、客户命名惯例，你一遍又一遍地贴。Skill 把这种重复变成一个文件，让 AI 在需要时自己加载。
什么是 Agent Skill？
Agent Skill 是一个文件夹，里面放着单一的 SKILL.md 文件：开头是 YAML frontmatter，包含名称与描述，接着是 Markdown 正文，写明逐步操作指示。AI 先读描述判断何时该用，然后才在那一刻加载正文。旁边可以另外放脚本与参考文件。
Anthropic 于 2025 年 10 月发布 SKILL.md 格式，并在官方 Agent Skills 文档中详细说明。此后这个格式已扩散到 Claude 以外的工具，意味着你写一次，就能在多个 AI 工具间重用，不需转换格式。
它与「保存起来的提示词」最实质的分别在于触发机制。保存的提示词躺在文档里，等你记得去粘贴。Skill 则由 AI 根据描述自行判断，任务吻合时自动加载。
它与 Custom GPT 或 Project 的分别则在于可移植性与范围。Project 的指令套用在里面所有内容之上；Skill 只在它所描述的任务上生效，所以你可以安装三十个，而每次只加载相关的那一个。
渐进式披露如何运作？为何它关系到你的上下文窗口？
渐进式披露（progressive disclosure）指的是：AI 在启动时只看见各个 Skill 的名称与描述，判断相关后才加载完整的 SKILL.md 正文，需要具体细节时才打开更深层的参考文件。这让你安装三十个 Skill，也不会在你打第一个字之前就把上下文窗口塞满。
三个层级如下：
--- 第一层，发现层。任何时候都只有 YAML 的名称与描述留在上下文中，每个 Skill 约占 80 个 token。二十个 Skill 的常驻成本约为 1,600 个 token。
--- 第二层，启用层。AI 判定相关后，完整 Markdown 正文才加载。正文长度通常由精简版的约 275 个 token，到大型 Skill 的约 8,000 个 token 不等。
--- 第三层，参考层。正文所链接的文件，例如风格指南或数据结构定义，只有在 AI 真正需要时才加载。
这正是官方撰写指引建议 SKILL.md 正文保持在 500 行以内的原因。超过之后，你就是在为 AI 未必用得上的指令支付启用成本。多出来的部分应拆成参考文件。
对你撰写时的启示很明确：把「判断」放进正文，把「查阅资料」放进参考文件。一份检查清单属于正文；一份四十页的品牌手册则不属于。
描述字段要怎样写，Skill 才真的会被触发？
描述字段是触发器，不是说明文档。它必须同时交代这个 Skill 做什么、以及何时使用，长度须在 1,024 字符以内。描述写得含糊，是 Skill 永远不被触发的头号原因，因为 AI 就是拿你的请求去比对这段文字，没有其他依据。
把它当作「比对面」来写，而不是摘要。务必写入你实际会打出来的具体名词与说法。
不会触发的弱描述：
--- description: Helps with writing tasks.
这里完全没有交代是哪一类写作任务，于是它要与其他所有沾边的写作 Skill 竞争，通常都会落败。
会触发的强描述：
--- description: Draft and edit LinkedIn posts in the company voice. Use when the user asks to write a LinkedIn post, turn an article into a post, rewrite a draft for LinkedIn, or mentions "LinkedIn", "social post", "thought leadership post". Covers hook, body structure, and hashtag rules.
三个习惯造成关键差别。第一，指名产出物本身，写「LinkedIn post」而不是「content」。第二，用你自己的说法列出触发字眼，包括那些不够工整的口语表达。第三，明确划出边界，让 AI 知道这个 Skill 不负责什么。
另有一点值得留意：描述写得太广，与写得太含糊同样糟糕。如果你写「适用于任何内容任务」，它就会拦截自己根本处理不好的请求。
SKILL.md 正文应该写什么？一份可直接复制的模板
正文是 Skill 加载后 AI 要跟随的程序。有效的正文通常包含四个部分：何时该用与何时不该用、所需输入、编号步骤，以及质量检查清单。要把它写成给一位能干新人的指示，而不是对流程的描述。
以下是一个完整的 Skill，你可以直接复制、改名，大约十五分钟就能调整成自己的版本。
试试看：保存为 .claude/skills/meeting-notes/SKILL.md
---
name: meeting-notes
description: Turn a raw meeting transcript or rough notes into a structured summary with decisions, owners and deadlines. Use when the user pastes a transcript, uploads meeting notes, or asks to "summarise the meeting", "write up the call", "pull the action items", or "what did we decide". Produces a fixed 4-section format.
---
# Meeting Notes
## When to use
Use when the input is a transcript, recording summary or rough notes from a real meeting.
Do NOT use for drafting an agenda before a meeting, or for one-to-one performance conversations.
## Inputs required
- The transcript or notes.
- If missing, ask once: who attended, and what was the meeting for?
## Steps
1. Read the whole input before writing anything.
2. Produce exactly four sections: Decisions, Action items, Open questions, Context.
3. Decisions: one line each, past tense, no hedging. Only what was actually agreed.
4. Action items: format as "Owner - task - deadline". If no owner was named, write "UNASSIGNED" rather than guessing.
5. Open questions: anything raised and left unresolved.
6. Context: maximum 3 sentences, for someone who missed the meeting.
## Quality checklist
- Every action item has an owner field, even if UNASSIGNED.
- No invented deadlines. If a date was not stated, write "no date set".
- Total output under 400 words.
留意这份正文没有写什么：没有解释「会议是什么」，没有铺陈式的开场白，也没有「你是一位乐于助人的助手」。每一行不是规则，就是限制。
也请留意当中两道防线。「宁可写 UNASSIGNED 也不要猜」与「不得杜撰期限」之所以存在，是因为模型在数据缺口处会很有信心地自行填补。防线要写成明确指令，而不是心存侥幸。
不写代码的话，如何安装与测试 Skill？
把文件夹放进 .claude/skills/ 即可套用于单一项目，放进 ~/.claude/skills/ 则全局可用。没有编译步骤，没有终端命令，没有软件包要安装。之后就用你平时的说法提出请求，看 Skill 会不会被加载。
测试是最多人略过的一步，也正是 Skill 悄悄失效的地方。请执行以下三项检查。
--- 触发测试。用三种不同的自然说法提出同一个请求。如果只有其中一种触发成功，代表你的描述欠缺你实际会用的词汇，补上去便是。
--- 误触测试。提出一个相邻但不应该由它处理的请求。以上面的会议记录 Skill 为例，试试「帮我草拟明天会议的议程」。如果它被触发，代表描述太广，需要收紧「Do NOT use」那一行。
--- 输出测试。用三份确实不同的输入去跑，其中一份要故意杂乱。只在干净输入下有效的 Skill 是演示品，不是工具。
触发不准时，先修描述；输出不对时，才修正文。把两者混在一起改，正是很多人最后得到一个三百行却依然不会触发的 Skill 的原因。
Agent Skill 在哪些地方会失效？
Skill 的失效方式有四种，而且相当可预测：描述含糊到无法触发、正文膨胀超过 500 行、多个 Skill 范围重叠互相竞争，以及指令假设了 AI 并不掌握的背景。这四项都不是模型能力的限制，全部都是撰写问题，你都可以修正。
范围重叠是最令人意外的一项。当你有八、九个 Skill 之后，总会有两个描述到相近的领域，而 AI 的选择会变得不稳定。解法是在每一段描述中写明边界：讲清楚它不涵盖什么，并指名由哪一个同类 Skill 处理。
Skill 不会把弱模型变强。它提供的是程序与限制，不是能力。如果底层模型连在一个写得好的一次性提示中都无法稳定完成该任务，把它包装成 Skill 也改变不了结果。
Skill 同样不保证输出完全一致。同一个 Skill 处理同一份输入，每次的输出不会逐字相同。如果你需要严格重现，例如固定的表格结构，就要在正文中明确写出结构，并加进质量检查清单。这能让你接近一致，但不等于零变异。
还有一个值得养成的安全习惯：Skill 本质上是会被执行的指令文字。从公开目录下载的 Skill，安装前请先读一遍，就像你会查看浏览器扩展索取的权限一样。
立即动手：20 分钟写出你的第一个 Skill
回想过去一个月，你最常粘贴进对话的那段指令是什么。那就是你的第一个 Skill。整个练习约需 20 分钟，而每一次省下粘贴的动作，回报都会累积。
用以下提示词取得初稿，然后自己动手改。不要直接使用初稿，因为模型并不知道你真正的触发词汇。
可直接复制的提示词：
I want to turn a repeated instruction set into an Agent Skill in SKILL.md format.
Here is what I paste into chat every time:
[PASTE YOUR USUAL INSTRUCTIONS]
Here are three ways I actually phrase the request:
1. [PHRASING 1]
2. [PHRASING 2]
3. [PHRASING 3]
Write a complete SKILL.md with:
- YAML frontmatter: name (kebab-case) and description under 1024 characters that states what it does AND when to use it, incorporating my three phrasings verbatim.
- A body under 150 lines with these sections: When to use / Do NOT use, Inputs required, Steps (numbered), Quality checklist.
- At least two explicit guardrails against the model inventing information.
Then list three adjacent requests that should NOT trigger this skill, so I can test for false positives.
保存输出、安装、跑完三项测试，然后写第二个。第二个只需十分钟。
如果你挑中的重复任务主要是在不同应用之间搬数据，而不是处理文字，Skill 未必是合适的容器。我们对 Zapier、Make 与 n8n 的比较说明了什么情况下无代码自动化平台才是更好的选择。
核心结论
用得不错与用得很好的分别，很少来自提示词写得多巧妙，而在于一件事：你那些好指令，究竟是存在 AI 找得到的文件里，还是留在你不断重贴的草稿本上。
Agent Skill 用纯 Markdown 就能补上这道落差。描述当作触发器来写，正文控制在 500 行以内，测试误触情况，并且诚实面对一点：Skill 提供的是程序，不是能力。
最后这一点最值得记住。工具应该减少你需要记住的事，而不是增加。懂AI，更懂你 UD相伴，AI不冷。
本文由 UD AI 团队审阅。
把一个 Skill 变成一整套运作系统
写出第一个 Skill 是最容易的部分。真正令人卡住的，是把整个团队的工作跑在 Skill 之上，并接上你实际使用的工具与数据。UD 团队手把手带你完成每一步，由盘点哪些任务值得封装，到配置、测试与正式部署。
