写 Skill 的重点不在堆知识，而在明确触发条件、固定执行路径，并持续验证稳定性。

Skills 设计：重点不是知识，而是稳定执行

Skill 最有价值的地方，不是多塞一点提示词，而是让 Claude 在合适的时候，按固定方法把任务做完。 所以写 Skill 时，重点不该放在“介绍 Skill 是什么”，而该放在三件事上：

  • 什么时候触发
  • 触发后按什么步骤执行
  • 怎么验证它真的比不用 Skill 更稳定

先设计 use case，不要先写模板

官方指南里最实用的一点是：先定义 2 到 3 个具体 use case，再开始写 Skill。不是“做一个文档生成 Skill”，而是这种粒度：

  • 用户会怎么提需求
  • 需要哪些步骤
  • 哪一步最容易出错
  • 最终结果长什么样

例如：

Use Case: Sprint Planning
Trigger: "帮我规划 sprint" / "创建这周任务"
Steps:
1. 拉取当前项目状态
2. 分析优先级和容量
3. 生成任务建议
4. 回写到项目系统
Result: 一组可执行的 sprint tasks

如果这些内容还没想清楚，Skill 基本也写不清楚。

frontmatter 决定了 Skill 会不会被用到

Anthropic 文档里强调得很直接：YAML frontmatter 是最重要的部分，Claude 主要靠它判断要不要加载 Skill。最核心的是 description，它必须同时说清两件事：

  • 这个 Skill 做什么
  • 用户在什么场景下会需要它

一个简单好用的写法是：

[做什么] + [什么时候用] + [边界]

例如：

description: Manage Linear sprint planning, task creation, and backlog prioritization.
Use when user asks to plan a sprint, create tickets, prioritize backlog,
or update Linear tasks.

坏写法通常有两种：

# 太泛
description: Helps with projects.

# 只有实现视角，没有用户视角
description: Implements hierarchical project entity operations.

如果 Skill 不触发，优先改 description。如果 Skill 乱触发，就把范围收窄，并补上负向边界。

例如：

description: Advanced CSV statistical analysis for regression, clustering, and modeling.
Use when user asks for statistical analysis of CSV data.
Do not use for simple charts or spreadsheet cleanup.

正文别写成说明书，要写成执行骨架

一个好 Skill 的正文通常不需要很长，但必须让 Claude 能直接执行，而不是自己猜。最实用的结构就是：

## When To Use
## Steps
## Troubleshooting
## Output

关键不是标题，而是内容必须可操作。

差的写法：

先检查一下数据，然后做适当处理。

好的写法：

Run `python scripts/validate.py --input {filename}`.
If validation fails:
- Missing required fields: add missing columns
- Invalid date formats: convert to YYYY-MM-DD

前者是提示词，后者才是工作流。

SKILL.md 只放核心流程，细节拆出去

官方指南反复强调 progressive disclosure。对写作者来说，最直接的落地方式就是：

  • SKILL.md 只放触发条件、步骤、输出格式、错误处理
  • 长文档、API 规则、风格规范放到 references/
  • 可重复执行的收集和校验动作放到 scripts/

引用 supporting files 时也不要写得太虚。最好直接写清用途：

Before writing API queries, consult `references/api-patterns.md` for:
- rate limiting
- pagination
- error codes

这样 Claude 知道什么时候该读、该读哪一份、为了解决什么问题而读。

三类 Skill，写法不同，但核心标准一样

Anthropic 在文档里总结了三类常见 Skill，我觉得可以直接对应成三种写法。

1. 产物生成型

比如页面、文档、报告、代码生成。重点不是“能生成”，而是：

  • 输出结构稳定
  • 风格一致
  • 有交付前检查

2. 工作流自动化型

比如发布、迁移、初始化、数据处理。重点是：

  • 步骤分阶段
  • 每步有校验
  • 出错有回退

3. MCP 增强型

MCP 提供工具访问，Skill 提供方法论。 没有 Skill 的 MCP，常见问题不是“不能调用工具”，而是“调用了，但流程不稳定，结果也不一致”。

不要只测“能不能跑”，要测触发和稳定性

官方指南里很值得抄的一点，是把测试拆成三层。

1. 触发测试

  • 明显相关的请求会不会触发
  • 同义改写后还会不会触发
  • 无关请求会不会误触发

2. 功能测试

  • 流程能不能跑通
  • 输出对不对
  • API 或 MCP 调用稳不稳定
  • 异常分支能不能恢复

3. 性能对比

  • 有没有减少消息轮次
  • 有没有减少工具调用
  • 有没有减少用户纠正
  • 有没有减少失败调用

如果用了 Skill 以后，用户还是要反复补 prompt、补步骤、补约束，那这个 Skill 还不够好。

迭代时重点看三种失败信号

1. Under-triggering

表现：该触发时不触发。

处理：补用户真实会说的话，补任务名、文件类型、场景词。

2. Over-triggering

表现：不相关请求也触发。

处理：收窄范围，补上 “Do not use for …” 这类负向边界。

3. Execution issues

表现：结果不稳定，用户总要修正。

处理：把模糊表达改成可执行动作，加校验步骤，加错误处理。

最容易写废 Skill 的几种方式

  • description 太泛
  • 只有能力描述，没有触发条件
  • 正文全是抽象动词，比如“分析一下”“适当处理”
  • 把长篇资料全塞进 SKILL.md
  • 一个 Skill 同时覆盖好几类任务
  • 没有输出格式
  • 不测误触发和异常分支

一个更务实的写法

  1. 先挑 2 到 3 个高价值、可重复的 use case
  2. 先在真实对话里把一个难例跑通
  3. 把成功路径压缩成清晰的 description 和步骤
  4. 把长资料拆进 references/，把确定性动作放进 scripts/
  5. 用触发测试、功能测试、性能对比持续迭代

Skill 写得好不好，最后看的是一件事：Claude 能不能在更少提示下，更稳定地把任务做完。

参考