Skill 不是 Prompt——
它是结构化的行为设计。

什么是Agent Skill

在 AI Agent 生态中，Skill 是一种可复用的提示词增强包，通过渐进式加载 机制为 Agent 注入领域知识与工作流。2025 年 12 月 Anthropic 把它作为开放标准发布，目前 已被 33+ 个 Agent 产品采纳——Claude Code、OpenAI Codex、Cursor、Gemini CLI、Kiro 等。

最小形态

一个 Skill 的最小形态只需要一个文件：

SKILL.md 由两部分构成：YAML frontmatter（元数据，告诉 Agent 这是什么、何时用）和 Markdown body（指令正文，告诉 Agent 怎么做）。

三层渐进式加载

这是 Skills 规范最精妙的设计——借鉴 UI/UX 领域的渐进式信息披露策略。 即使安装了 20 个 Skill，初始加载也仅 1000-2000 tokens。 相比单体式提示词，上下文使用量减少约 90%。下面这个交互演示了 Agent 如何按需逐层展开。

关键价值在于分层激活的时机判断：Skill 的触发完全依赖 description 字段， 由模型自主判断当前任务是否匹配，而非关键词硬编码。这意味着写好 description 比写好指令主体更关键。

SKILL.md 的字段约束

YAML frontmatter 有两个必填字段、四个可选字段。命名规则比想象中严格——下面是完整的字段表与 最容易踩的坑。

name 字段——容易踩的坑

name: pdf-processing
name: data-analysis
name: code-review

name: PDF-Processing    # 不允许大写
name: -pdf              # 不能以连字符开头
name: pdf--processing   # 不允许连续连字符

description——决定触发率的字段

触发完全依赖 description，不要把它当成"装饰说明"来写。三个写作要点： 使用祈使语气（Use this skill when...）、聚焦用户意图（而非 Skill 内部机制）、 包含可能的关键触发词。

Analyze CSV and tabular data files —
compute summary statistics, add derived
columns, generate charts, and clean
messy data. Use this skill when the
user has a CSV, TSV, or Excel file and
wants to explore, transform, or
visualize the data, even if they don't
explicitly mention "CSV" or "analysis."

Helps with PDFs.

三个可选目录的分工

三个目录承担不同角色——记住一条：每个文件保持聚焦，因为 Agent 是按需加载的，文件越小消耗越少。

Skill-Creator——把 ML 工程搬进 Prompt Engineering

Anthropic 官方"用来创建 Skill 的 Skill"。设计哲学一句话：像做机器学习一样做 Prompt Engineering—— 有训练集、测试集、评估指标、迭代循环、防过拟合机制。 它把软件工程中的 CI/CD、A/B 测试、性能基准这套实践完整移植过来了。

三个核心思想

六阶段生命周期

点击下面任一阶段查看详情。注意：3 → 5 是一个迭代回路，不是线性过程。

三个专业化子 Agent

各司其职，形成完整评估链。最精妙的是 Grader 的"自我批评"机制——它不仅打分，还质疑断言本身的合理性。

JSON 数据流——7 种 Schema 的级联管道

references/schemas.md 定义了 7 种 JSON 结构，形成完整的数据管道。每一步的输出是下一步的输入。

客观评价

Writing-Skills——把 TDD搬进 Skill 开发

Superpowers 框架里的元技能。它和 Skill-Creator 目标相似但方法论截然不同—— 不是统计基准，是 RED → GREEN → REFACTOR 的测试驱动循环。核心理念：测试先行、系统化优于随机化、 复杂度缩减、证据优于声明。

RED-GREEN-REFACTOR 循环

这是 TDD 的经典三段，搬到 Skill 开发场景里。

四种 Skill 类型 · 对应不同测试策略

不是所有 Skill 都需要压力测试。先识别类型，再选测试方法。

关键差异：纪律执行型需要最严格的测试（压力 + 借口反驳），参考资料型主要测信息可发现性。 用错测试方法，要么过度工程，要么漏洞百出。

最重要的发现——Description 只描述触发条件

为什么？测试发现，当 description 总结了工作流程时，Agent 可能直接按 description 执行，跳过阅读完整 Skill 内容。 这是个反直觉但关键的洞察。

description: Use when executing
  plans - dispatches subagent per
  task with code review between
  tasks

description: Use when executing
  implementation plans with
  independent tasks in the current
  session

Anthropic 官方最佳实践要点

简洁是关键——上下文是公共资源。默认假设 Claude 已经很聪明，只添加它不知道的信息。

## Extract PDF text
Use pdfplumber for text extraction:
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

## Extract PDF text
PDF (Portable Document Format) files
are a common file format... To extract
text from a PDF, you'll need to use
a library... There are many libraries
available...

设置合适的自由度

Google 总结的5 种内部结构

规范告诉我们"Skill 长什么样"，但没告诉我们"Skill 内部逻辑该怎么设计"。Google ADK 团队研究了 Anthropic 仓库、Vercel 和 Google 内部指南后，归纳出 5 种反复出现的设计模式。点击下面任一模式查看 它的可视化、内部代码与适用场景。

哪种模式适合你？

面对一个新需求，按主问题选模式，必要时考虑组合。下面是交互式选择器——点击你的诉求，看推荐结果。

组合策略——单一模式不够时

5 种模式不是互斥的。下面是社区里被验证过有效的组合方式。

方法论选择——Skill-Creator vs Writing-Skills

两种方法论都有其位置——不是非此即彼，而是看场景。