打造高效易用的Agent Skill

第二级：SKILL.md 的正文。只有当 Agent 判断出某一个 Skill 跟当前任务存在关联的时候，才会去读取 SKILL.md 的完整内容。SKILL.md 当中含有关键指令、工作流程以及关键示例。

处于第三级别的是，名为 references，/ 的目录以及名为 scripts，/ 的目录。在 references，/ 目录里所存在的详细文档 ，还有在 scripts，/ 之下的可执行脚本 ，它们只有在 Agent 执行的流程当中 ，当确实有需要的时候 ，才会被去进行查阅或者调用。

为什么要这么设计？它解决了两个实际问题：

Token效率方面，并非将全部知识一下子都放进上下文里，以此防止出现信息过载的情况。注意力聚焦方面，模型的注意力机制在上下文越长的时候，其衰减就越发显著，渐进式披露能让模型在每一个阶段只专注于最为相关的信息。

1.4 怎么组织和安装 Skill

随着Skill的数量不断增多，它分散于各个地方，很快便会失去控制。建议从一开始就借助Git仓库进行统一管理。

team-skills/
├── code-review/
│   └── SKILL.md
├── react-state-management/
│   ├── SKILL.md
│   └── references/
├── sprint-planning/
│   ├── SKILL.md
│   └── scripts/
└── ...

好处很直接：版本有记录，团队能协作，跨仓库安装迅速。

Agent 平台具体安装之时，各家路径约定参差不齐，不过社区已然推出统一解决办法，Vercel 开源的 skills CLI 工具，一条命令可兼容多个平台：

# 从 GitHub 安装，自动识别当前环境并放到正确的位置
npx skills add https://github.com/your-team/skills/tree/main/code-review
# 支持 Claude Code、Cursor、Windsurf 等主流 Agent 平台
# 无需关心各平台的路径差异

当然啰，你同样能够凭借手动方式去进行放置安装。由于平台以及场景存在差异，所以路径约定并不相同，就拿Claude Code来说便是如此。

Claude Code：

# 项目级（只在当前项目生效）
.claude/skills/code-review/SKILL.md
# 全局级（所有项目生效）
~/.claude/skills/code-review/SKILL.md

社区实践一瞥

技能的生态正处于快速成长的状态，Anthropic官方给出了一批具备高质量的技能，在anthropics/skills仓库当中，特别是pdf、技能创建者、前端设计这几个方面，它们很好地展现出了渐进式披露，与脚本自动化的最佳实践，这些技能本身就是上等的学习范本。

在社区这个层面，Asana、Atlassian、Figma、Sentry、Zapier这些厂商，已经给自己的MCP Server配备了Skill。独立开发者也在持续进行贡献，从前端设计一直到代码审查，从数据分析一直到项目管理范畴，可用的Skill库正在不断地扩大。

02 如何编写一个 Skill

2.1 基本格式

一个 Skill，于文件系统里是一个文件夹，其最小结构仅需一个文件。

your-skill-name/
├── SKILL.md          # 必须，入口文件
├── scripts/          # 可选，可执行脚本
├── references/       # 可选，参考文档
└── assets/           # 可选，模板、图标等资源

命名规则简单但严格：

SKILL.md的结构，划分成了两部分，一部分是YAML Frontmatter，另一部分是Markdown正文。

---
name: my-skill-name
description: 做什么。在用户说"XXX"时使用。核心能力包括 A、B、C。
---
# My Skill Name
## Instructions
具体的指令内容...

---包裹Frontmatter，其中必填字段是为name以及description。正文编写采用标准Markdown，其含有Agent执行任务时需遵循的具体指令。

2.2 工作原理

领会Skill的工作运转机制，会对对撰写出更具成效的Skill有所帮助。其核心的流程是这般的：

在阶段一，也就是常驻索引阶段，你所安装的全部Skill的description字段，会被注入到Agent的系统提示词里面，而Agent在每一次对话开始的时候，就处于“知道”自身拥有哪些Skill的状态，不过却对具体内容并不知晓咯。

第二步：启动读取，在用户的请求同某些Skill的description相匹配之际，Agent会运用内置工具（像view或者read命令）去读取该Skill的SKILL.md全部内容，此步骤对应于messages里的一项工具调用。

阶段三：进行执行以及深入，Agent依据SKILL.md里的指令着手开始执行任务，要是指令当中引用了references/之下的文档或者scripts/之下的脚本，Agent会在有需要的时候再度去进行读取或者执行它们。

从 API 的 messages 这个视角去看，存在着一个典型的 Skill 调用，大致是这样的。

用户消息 → Agent 识别需要 Skill → [工具调用: 读取 SKILL.md] 
→ Agent 获得指令 → [工具调用: 执行任务步骤] → 返回结果

这表明，Skill 的激活这件事本身，会耗费 1 到 2 步工具调用。所以，description 写得是否准确，会直接对 Token 消耗以及响应速度产生影响，误触发就意味着造成浪费，漏触发则意味着存在能力缺失。

03 编写优质的 Skill

一个Skill能否被使用以及使用起来是否好用，二者之间存在着巨大差距。这种差距主要在两个方面有所体现：Description决定了“何时去使用”，Body决定了“使用起来会产生怎样的效果”。

3.1 Description：激活的精准度

Description是整个Skill体系里最为关键的那一行文字，它决定着Agent在何种场景之下会加载你的Skill，若是写得欠佳，要么在该用之时不会触发，也就是under-triggering，要么在不该用的时候胡乱触发，即over-triggering。

三大要素，一个优秀的描述，要同时回应三个问题，这是其一，其二，其三。

如下这些方面：就这个Skill来说能实现怎样的作为，其深层次的价值究竟是什么，具体所涵盖的能力内容都有哪一些，当用户表述了哪些话语、实施了怎样的操作之际应当促使其启动。

正面案例：

# 清晰、具体、包含触发短语
description: >
  分析 Figma 设计稿并生成开发交付文档。当用户上传 .fig 文件、
  要求"设计规范"、"组件文档"或"设计转代码交付"时使用。

# 明确的服务边界和触发词
description: >
  管理 Linear 项目工作流，包括迭代规划、任务创建和状态跟踪。
  当用户提到"迭代"、"Linear 任务"、"项目规划"或要求
  "创建工单"时使用。

反面案例：

# 太模糊，几乎什么都能匹配
description: Helps with projects.
# 缺少触发条件，Agent 不知道什么时候该用
description: Creates sophisticated multi-page documentation systems.
# 过于技术化，没有用户视角的触发词
description: Implements the Project entity model with hierarchical relationships.

具备防止过度触发的技巧，要是你的Skill常常于不相关的场景当中被加载，那么能够在Description里添加"负向触发"的说明。

description: >
  CSV 文件的高级数据分析，包括统计建模、回归分析、聚类。
  不要用于简单的数据浏览（那个用 data-viz skill）。

3.2 Body：执行的效果

描述撰写好了，只是要让技能在恰当的时间现身，身体的质量才对最终效果起着决定性作用。依照使用场景，身体通常展现出两种形态：

形态一：知识文档型

这适用于一些场景，在这些场景当中，需要Agent去掌握特定领域的知识，或者是能遵循特定的标准。

核心要素：

## Code Review Standards
### Critical Checks (must pass)
1. No hardcoded credentials or API keys
2. All user inputs sanitized
3. Error boundaries on async operations
### Quality Checks (should pass)
1. Functions under 50 lines
2. Meaningful variable names (no single letters except loop counters)
3. Comments explain "why", not "what"
### Example Review
**Input:** A React component with inline styles and no error handling
**Expected output:**
- Flag: inline styles → suggest CSS modules or Tailwind
- Flag: missing error boundary → provide template
- Pass: component size reasonable
- Suggestion: extract magic numbers to constants

形态二：工作流型

适用于多步骤、有固定流程的任务。

核心要素：

## Sprint Planning Workflow
### Step 1: Gather Context
Fetch current project status from Linear.
**Validation:** Confirm at least 1 active project returned.
### Step 2: Analyze Velocity
Calculate team velocity from last 3 sprints.
**Validation:** Velocity data covers at least 2 complete sprints.
### Step 3: Draft Plan
Create task breakdown with estimates.
**Validation:** Total story points ≤ average velocity × 0.85 (buffer).
### Step 4: Review & Adjust
Present plan to user. If user requests changes:
→ Return to Step 3 with modified constraints.
### Step 5: Execute
Create tasks in Linear with labels and assignments.
**Validation:** All tasks created successfully, no API errors.

3.3 进阶技巧：分层与自动化

SKILL.md 将多层渐进用以放置核心指令以及工作流主干而非其他，详细的API文档，、完整的示例库、边缘场景的具体处理方案，会放置于 references/ 目录之下，并且在正文里会以使引用路径明确的方式来引用上述内容：

Before writing API queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns  
- Error codes and handling

如此一来，既能确保 Agent 晓得存在这些可供使用的资源，又不至于在每一次激活之际都去加载一应俱全的内容。

脚本自动化，对于那些能够借助代码以确定方式完成的事儿瞧，切莫让模型凭借自然语言“理解”着去开展操作，因为模型理解自然语言存在概率性，然而代码执行具备确定性。

这个模式被官方的PDF、DOCX、PPTX等Skill大量运用，核心的文档生成方面的逻辑被封装于Python脚本当中，SKILL.md仅仅承担告知Agent何时去调用哪一个脚本、传递什么样的参数的职责。

04 基于评测迭代

完成 Skill 并非是重点所在，Skill 实际上是针对概率性系统所编写的指令，在“我认为写得相当不错”与“其的确在各类场景之中都展现出稳定表现”之间，常常存在着历经好几轮迭代的差距，评测并非是起到锦上添花的作用，而是 Skill 开发流程里不可予以省略的一个环节。

4.1，核心理念指，要像运用对待 Prompt 那般，去运用一样对待 Skill。

Skill的Description属于系统提示词的一部分，Body是任务执行期间的指令集。这致使Skill开发以及Prompt开发面临类似的挑战，而Prompt开发存在一个经反复证实的基本情况：你没办法凭借直觉判定一段指令的优劣，只能借助在真实场景里反复测试去验证。

这引出三个关键原则：

原则一：进行分层评测，Description所解决的是与Body截然不同的问题，前者决定的是“什么时候去使用”，而后者决定的是“使用起来会呈现怎样的效果”，它们在评测方法方面存在差异，在评测标准方面也不一样，其迭代策略同样完全不同，因此必须要分开来进行处理。

原则二为，对照实验。“好不好”属于相对概念。一个Skill的输出质量 ，唯有与某个基线进行对比才具备意义。这个基线能够是没有Skill时的裸跑效果 ，也能够是上一个版本的Skill。若没有对照组 ，改进便无法得以衡量。

原则三：人类参与其中。自动化评分可以覆盖格式方面、结构方面、字段完整性这类客观检查，然而 Skill 真正具有的价值，像是审美判断、业务适配度、专业深度等方面，只有人方可进行评估，评测流程的设计务必要使人类的判断能够高效地注入迭代循环之中了。

4.2 评测 Description：触发的精准度

测试评估需要去回应一个简易的问题：智能体在应当运用这个技能的时刻运用了吗？在不应该运用的时刻没有运用吧？

理解触发机制

在动手测之前，先理解两个关于触发的事实：

事实一：Agent 只会在自认为搞不定之时，才会去找 Skill。对于简单的一步操作（诸如“读一下这个文件”），哪怕 Description 绝妙吻合，也有可能不会触发，这是由于 Agent 判断自身能够直接完成。这就表明，你的测试用例务必足够复杂，否则你所测试的并非 Description 是否良好，而是任务的难度够不够。

事实二：Agent 天生存在偏向欠触发（under-triggering）的情况。Description 要写得更具主动性，将边界向外拓展。例如，不能仅仅写“分析 Figma 设计稿并生成交付文档”，而是要追加内容，当用户提及设计规范、UI 组件文档、设计转代码交付，甚至只是上传了 .fig 文件但未明确说明要做什么的时候，都应当使用。

另外存在一个常见的错误情形，那就是将关于“什么时候该用到这个Skill”的有关讯息书写在Body里面，Body是在触发以后才会进行加载的，如此书写并没有起到任何的助益作用，所有与触发相关联的信息，都必须且仅仅能够书写在Description当中。

构建评测集

准备 16-20 条测试 query，分两组：

[
  {
    "query": "我们团队要移除 less-loader，把 .less 文件全部转成 PostCSS 方案。项目比较大有 200 多个 LESS 文件，有复杂的 mixin 嵌套，用哪种方式风险更低？",
    "should_trigger": true
  },
  {
    "query": "项目已经在用 PostCSS 了，现在想加 postcss-px-to-viewport 做移动端适配，postcss.config.js 不知道怎么写。",
    "should_trigger": false
  }
]

构建评测集时最容易踩的坑：

执行评测

逐一条目地，将用于测试的query发送给Agent，去观察它是不是加载了与之对应的Skill。把结果记录下来，运算两个指标：

一个快速调试技巧：直接问 Agent "你什么时候会使用

skill-name

这个名为Skill的东西，它具有将Description加以复述后返回的能力，借助此能力你能够依据其复述情况判断是否符合你原本所设的意图，从而进行不断地迭代改进。

从失败的情况事例当中，剖析探究其形成的缘由，进而对描述说明进行调整：

于每次修改完毕之后，运用完整的评测集再次运行，将前后所获得分予以对比，留意切莫仅仅紧盯失败的情形去开展针对性的修补。描述最终所需直面的具体系无穷多种真实的查询，过度拟合至几条测试用例是毫无意义的。

4.3 评测 Body：输出质量

由于“好不好”并非布尔常量，而是一种多维度的质量判定，所以Body的评测相较于Description要繁杂得多，核心方式是具备Skill与不具备Skill的对比试验。

Step 1：设计测试用例

准备 2-5 个代表性的测试任务。好的测试用例有几个特征：

针对每个测试用例，准备好输入材料，其中包括需要审查的代码，需要分析的数据，需要处理的文档等。

Step 2：对照实验

对每个测试用例，分别跑两次：

核心要求为：借助相同的 Agent，运用相同的输入内容，处于相同的系统环境之中。而仅仅存在一个变量，那便是 Skill 的有无状况或者版本存在差异。

把输出保存在结构化的目录中，方便后续对比：

eval-workspace/
├── iteration-1/
│   ├── test-case-auth-module/
│   │   ├── with-skill/
│   │   └── baseline/
│   ├── test-case-api-refactor/
│   │   ├── with-skill/
│   │   └── baseline/
│   └── ...

Step 3：定义评判标准

在查看结果之前，要先把“什么算好”想明白，以此来防止结果对标准产生影响。评判标准划分成了两个类别。

可程序化验证的客观标准，用脚本直接检测：

需要人判断的主观标准，形成检查清单：

对于写作风格，这属于高度主观的 Skill，设计审美，亦属于高度主观的 Skill，这类情况，并不需要去勉强定义细粒度标准，而是直接去看输出，然后做整体判断，如此一来，反而会更有效。

Step 4：评分和对比

逐个翻看每个测试用例的两组输出，记录：

关于客观检查项目最终的通过与否的情况，是通过运行脚本，然后统计其通过率，主观判断以及具体反馈方面，包括哪里表现良好，哪里存在不足，哪里出现了超乎预料的状况，反馈必须要书写得清晰详尽。“输出做得不够出色”这种情况缺乏行动上的指引，“在安全维度的审查环节遗漏了 SQL 注入风险，建议在 Skill 里增添 OWASP Top 10 检查清单”这样的内容才能够对改进效率起到指导作用。数据方面，如果能够获取到相关信息，要记录下 token 的消耗以及响应的时间，防止质量提升是以无法接受的效率作为代价来实现的。

最后得出一个明晰的判定：Skill版本于哪些方面比基线出色、于哪些方面保持一致、于哪些方面出现了倒退。

Step 5：分析和改进

修改Skill，是依据评分结果以及具体反馈来操作的，这一步骤属于整个迭代里极为需要判断力的环节，存在几个关键原则。

从反馈里头提炼出通用规律，别过度拟合到具体那些用例，Skill 最终是要在无数个不同的真实任务之上运行的，你现在仅仅是用几个测试用例去进行快速迭代，如果某个改动使得测试用例 B 的问题得到了解决但却让测试用例 A 出现了退步，很大概率你是在做过于针对性的调整，好的改动应当是普适的。

令指令维持精简状态，若能够获取 Agent 的执行进程（并非仅仅是最终输出），那就认真瞅瞅它究竟在做些什么，要是 Agent 耗费诸多步骤去做些毫无作用的事，那就找寻 Skill 里致使这些无用之事的指令，将其砍掉试试看，冗余的指令可不单单是浪费 token，还会使模型的注意力发生分散，进而降低真正关键指令的执行质量。

说明 why 而非堆砌 MUST。要是你发觉自身写出似 ALWAYS 或 NEVER 这般全大写的硬性约束，那就先停顿下来思索一番，可否改成阐释“为何此事至关重要”。待模型领会缘由后，其执行之时展现出的灵活性跟准确度通常会比单纯死记硬背的规则更为出色。硬性约束应当留存给那些切切实实不可违背的底线之处，而不是毫无节制地充斥于每一条指令当中。

在意重复开展的劳动，要是于多个测试用例的输出里头发觉 Agent 均独自编撰了相似的辅助脚本或者进行了相似的预处理工作，这表明此步骤就应该被提炼至 Skill 的 scripts/ 目录之下实施直接复用，而非每一回均让 Agent 自起炉灶。

常见问题和改进方向参考：

4.4 循环迭代

把上面的步骤连成闭环，每一轮迭代的流程是：

开展对照实验，于新目录之下，同时运行所有测试用例的实验组与对照组进行评分，针对客观指标运行脚本，对于主观维度借助人工判断予以分析反馈，即指出何处表现良好、何处出现退步、何处尚存在不足有待改进，凭借反馈对SKILL.md或者脚本予以修改，依照上述改进原则再次运行，运用完整评测集去验证改动所产生的效果。

你究竟想要回答何种问题，很大程度从而决定了对照组该如何去进行选择。要是你所面对的并非已有的 Skill，而是全新创建的 Skill，那么对照组所对应的便是没有 Skill 的那种类似裸跑的状态，在这样的情况下，你必须得拿出相应的论据来证实 Skill真切存在着价值。若你所要处理的是对已有 Skill 展开改进，那对照组的选取可以是旧版本，此时你需要切实证明所运用的改动能够带来积极的提升效果。

终止的条件是，反馈趋向于空白，也就是没什么要改了，或者你已经没有更多的手段去继续改进，又或者你对输出的质量感到满意了。不需要去追求完美，因为Skill和代码是一样的，能够持续迭代，在实际使用当中，当收集到新的失败case的时候，随时回来改进。

4.5 案例：Skill 迭代的实际路径

案例一：Skill-Creator 的三次进化

Anthropic官方的Skill - Creator，其自身经历了迭代式的演进，这种演进是逐步推进的，是不断变化发展的。

案例二：Code-Review Skill 的质量提升

一个更贴近业务的例子，代码审查 Skill 的迭代过程：

有两个版本，这两个版本在相同的20个PR上进行评测的跑动操作，通过Grader Agent来评估输出质量、覆盖率以及误报率，此过程之中，第二版在三项指标方面都显现出了明显的提升情况。

05 总结

正在统一 Agent 用以扩展能力的途径呢，是 Skill。从通过 MCP 提供的工具来进行连接，到借助 AGENTS.md 展开社区探索，再到采用 Skill 的标准化方案，Agent “学习新技能”的方式正趋于收敛。渐进式披露的设计，不但节省了 Token ，更为关键的是提高了模型的注意力分配效率。以自然语言作载体的知识表达，比起硬编码的逻辑来说，更为灵活，且更具 Agentic。

直接提升生成效果的是广泛的社区Skill，Anthropic官方的文档生成Skill（PDF、DOCX、PPTX）、前端设计Skill，和社区贡献的各类工作流Skill都能拿来即用，在你动手定制以前，先瞧瞧现有Skill能不能满足需求。

真正能让 Agent 在你的那个场景里头好用的重要的关键投入是定制的 Skill。通用的Agent能力就如同是刚进到你公司里头的那样的，虽说挺聪明可是却并不了解你公司业务状况的新人。而Skill，就仿佛是你交给他的专门关于工作方面的手册。Description那边的精准程度决定了它能够在恰当的场景里出现。Body这边的质量能决定它是怎样在场景里进行表现的。这两者，都是有着清晰明确的设计方面的原则以及可以去遵循的技巧的。

评测属于 Agentic 工程不可或缺的环节，不单单仅是工具开发需要评测，系统开发也要进行评测，就连 Skill 开发也是如此，绝非仅仅某一两项需评测，其他就无需评测。仅靠拍脑袋认定“差不多了”，与凭借数据证实“确实好了”，这两者之间常常差着好几轮迭代的距离。以评测为依据的循环式优化，即先评测，继之分析，再进而改进，而后重新评测，这是通向高质量 Skill 的可靠途径，没有别的更好办法，只能如此这般地循环往复，才有望达成高质量 Skill 的目标。

往后瞧，Skill 所做之事并非繁杂：把那原本你每次都需再度交代的经验，流程以及标准，加以整理一番且留存下来，而后 Agent 其自身便明白该如何去做了。省去重复性劳作，进而换来稳定且可预期的输出。

相关标签： # AgentSkill # Skill.md # 渐进式披露 # 评测迭代 # 社区实践