随着Claude Code、Codex、Cursor等智能编程工具逐渐从“代码补全助手”升级为可执行复杂任务的Agent，开发者开始需要一种能够长期复用业务经验的方法。过去，人们通常把代码规范、审查流程和输出模板全部写进System Prompt，但这种方式不仅占用大量上下文，也很难进行版本管理和质量评估。

Agent Skill解决的正是这个问题。它将特定任务需要的知识、流程、脚本和资源封装成独立能力包，并由模型根据当前任务按需加载。Anthropic官方将Skill定义为由指令、脚本和资源构成的文件夹，用于帮助Claude稳定、重复地完成专业任务。

一、Skill为什么不是普通Prompt

普通Prompt通常是一段临时指令，当前对话结束后便失去作用。Skill则具备持久化、模块化和可组合特征，能够放入项目目录，通过Git管理，并在多个会话中重复使用。

一个标准Skill目录可以写成：

code-review/
├── SKILL.md
├── scripts/
│   └── scan_security.py
├── references/
│   └── review-rules.md
└── assets/
    └── report-template.md

其中，SKILL.md负责定义触发条件与执行流程；scripts/存放Python、Bash或JavaScript脚本；references/保存较长的技术规范；assets/则用于存放报告模板、Schema或静态资源。

这种设计把“模型应该如何完成任务”从对话中抽离出来，使团队经验能够像代码一样沉淀、复用和迭代。

二、SKILL.md的标准格式

每个Skill必须包含SKILL.md，文件由YAML frontmatter和Markdown正文两部分组成。YAML告诉模型什么时候调用Skill，Markdown正文则描述Skill触发后应该执行哪些步骤。

---
name: code-review
description: >
  对Git diff、Pull Request或代码变更执行结构化审查。
  当用户要求检查代码缺陷、安全风险、性能问题或合并风险时使用。
license: MIT
compatibility: Requires Git and Python 3.10+
---

# Code Review Workflow

1. 读取当前Git diff。
2. 按严重、高、中、低四个级别分类问题。
3. 检查安全、性能、可维护性和测试覆盖情况。
4. 按模板输出审查报告。

有几项精确限制：name最多64个字符，只能使用小写字母、数字和连字符，并且要与目录名称一致；description长度为1至1024个字符；compatibility最多500个字符。Skill正文建议控制在500行以内，过长内容应拆分到参考文件。

三、三层渐进式加载如何节省上下文

Agent Skill最重要的设计是渐进式加载。

第一层是目录层。会话启动时只加载所有Skill的name和description，估算每个Skill约占50至100个Token。

第二层是指令层。只有当模型判断当前任务与某个Skill匹配时，才读取完整的SKILL.md正文，官方建议正文低于5000个Token。

第三层是资源层。脚本、参考文档和模板不会一次性进入上下文，而是在正文明确引用时才按需读取。

即使系统安装20个Skill，启动阶段也只需约1000至2000个Token，相比将全部规则塞进单体System Prompt，上下文占用可下降约90%。

四、description决定Skill能否被正确触发

Skill没有传统规则引擎，模型主要根据description自主判断是否加载。因此，描述不能只写“处理PDF”或“帮助审查代码”，而应同时说明能力、适用场景和触发表达。

# 过于模糊
description: Helps with code.

# 更容易正确触发
description: >
  审查Git diff和Pull Request中的缺陷、安全漏洞与性能问题。
  当用户提出code review、检查PR、分析代码风险或合并前审查时使用。

需要注意，description应该重点描述“什么时候使用”，不要把完整工作流全部写进去。描述过于详细时，模型可能直接依照摘要执行，反而跳过完整正文。

五、Skill-Creator如何把Prompt开发变成工程流程

Skill-Creator本身也是一个Skill，其目标不是简单生成一份Markdown，而是建立类似机器学习训练的开发流程。它强调三项原则：追求泛化而不是迎合少数测试用例；解释规则背后的原因，而不是堆砌ALWAYS和NEVER；发现重复操作后，将其提炼为可复用脚本。 其完整生命周期包含六个阶段：

需求捕获
→ 编写Skill
→ 设计并执行测试
→ 评分与人工评审
→ 迭代改进
→ 优化description并打包发布

测试阶段通常设计2至3个用例，并同时运行with_skill和without_skill两组任务，以判断Skill究竟带来了真实提升，还是仅仅增加了上下文。

在多模型应用中，团队还可以在模型调用层通过TreeRouter统一接入Claude、GPT、GLM等模型，减少不同SDK、接口地址和密钥配置的重复维护；Skill则继续负责定义任务触发条件、执行步骤与输出边界，两者分别解决模型接入和行为标准化问题。

六、三个评估Agent如何分工

Skill-Creator设计了三类评估角色。

Grader负责检查任务断言是否真正成立，而不是只看文件是否存在。Comparator在不知道结果来源的情况下对A、B两份输出进行盲评，内容正确性、完整性、准确性分别按1至5分评分，结构与可用性同样按1至5分评价，最后形成1至10分综合结果。Analyzer则负责揭盲，分析获胜方案的原因，并从指令、工具、示例、异常处理和结构等维度输出改进建议。

测试用例可以采用JSON保存：

{
  "skill_name": "code-review",
  "evals": [
    {
      "id": 1,
      "prompt": "检查这个JWT登录模块的安全问题",
      "expected_output": "包含安全风险分级的结构化报告"
    },
    {
      "id": 2,
      "prompt": "审查数据库迁移脚本是否存在数据丢失风险",
      "expected_output": "指出潜在破坏性操作并给出修复建议"
    }
  ]
}

这种方式让Skill优化从“感觉变好了”转变为可比较的通过率、Token消耗、耗时和输出质量。

七、工程化评估也有成本边界

Skill-Creator并非适合所有任务。以3个测试用例为例，一次评测可能产生6个执行Agent、3个Grader和1个Analyzer，总计10个子Agent。复杂Skill反复迭代时，调用量会快速增加。

GitHub Issue #514显示，一次包含20个评估查询、每个查询运行3次的description优化，会启动60个会话，并消耗约69%的5小时配额。该Issue建议使用较轻量模型执行触发判断，成本可能降低10至20倍。需要强调的是，这属于特定配置下的社区案例，不代表所有Skill评估都会产生相同消耗。

因此，简单的格式转换或固定模板任务可以直接手写SKILL.md；只有当任务存在复杂判断、多人维护、长期复用或严格质量要求时，完整评估体系才更有价值。

总结

Agent Skill的价值，不是把Prompt换成Markdown，而是将个人经验转化为可以版本管理、按需加载、自动触发和持续评估的工程资产。

SKILL.md解决行为定义问题，三层加载机制控制上下文成本，description决定触发准确性，而Skill-Creator则通过A/B测试、子Agent评分与迭代优化保证结果质量。对于准备构建企业Agent、代码审查系统或自动化研发流程的团队而言，真正需要掌握的已经不只是“如何写提示词”，而是如何设计、测试和维护一套可长期复用的Agent能力。