Claude Code Harness 12：Skills 从编写到演化

写 skills 最容易让人上头。因为它看起来像一个美好时刻------"终于可以把经验封装起来了"。然后就开始疯狂写：react-best-practice、typescript-best-practice、backend-best-practice、all-review-checklist。名字一个比一个像百科全书，问题也很统一：很长、很全、很正确------但 Claude 就是不一定触发，也不一定因为它们变稳。

这一章聚焦两件事：怎么写一个会改变 Claude 行为的 skill，以及怎么让系统从日常任务中持续沉淀出新的 skill。

一、Skill 是任务方法，不是知识存档

各层分工：CLAUDE.md 负责项目级总说明，Rules 负责长期约束，Memory 负责长期项目经验，Skill 负责某类任务怎么做。

一个 skill 的目标不是"把你知道的都告诉 Claude"，而是在某类任务里改变 Claude 的默认路径------把它最容易走错的方向重新拉回正确路径。

二、好 Skill 的三个核心要素

明确触发场景。 一个 skill 如果连"什么时候该触发"都模糊，就废了一半。坏的："高级前端开发最佳实践"。好的："用于中后台列表页筛选、分页、排序、批量操作相关功能的实现与审查。"后者具备场景、边界和触发信号。

改变默认行为。 如果一个 skill 只是告诉 Claude "写干净代码"、"注意可维护性"、"认真测试"------它没做什么，因为 Claude 本来就知道这些漂亮话。好的 skill 告诉 Claude 在这个任务里先做什么再做什么、哪些看起来顺手但不要做、什么叫完成。

高信号 Gotchas。 一个 skill 里最容易拉开价值差距的往往不是流程图，而是这个任务里 Claude 最容易踩的坑。比如：列表页筛选里 "all" 不是一个有效值而是"不传这个字段"；菜单隐藏不等于权限校验；导出接口不是同步下载是异步 job。

三、反例：坏 skill 长什么样

md 复制代码

# Next.js Best Practice

Use App Router.
Use server components where possible.
Use TypeScript.
Use clean architecture.
Use reusable components.
Use strong typing.
Use loading and error states.
Write maintainable code.
Think about performance.
Think about accessibility.

全是默认常识、没有任务边界、没有项目高信号信息。看起来很专业，但几乎不改变 Claude 的行为。

四、一个有用的 Skill 长什么样

以中后台列表页场景为例：

md 复制代码

# Admin Table Workflow

When to use:
- Building or modifying admin list pages
- Changing filter, pagination, sorting, or bulk action behavior
- Reviewing table-related regressions

Goals:
- Keep list state predictable
- Avoid breaking query/state sync
- Preserve API contract compatibility

Workflow:
1. Identify source of truth for filters and pagination.
2. Confirm whether URL, local state, or server params drive the table state.
3. Lock current behavior with targeted tests where feasible.
4. Make the smallest possible change to filters / sort / pagination flow.
5. Verify empty state, reset behavior, and permission-gated bulk actions.

Gotchas:
- `"all"` often means omit the filter param, not send `"all"` to the backend.
- Bulk action visibility is not the same as permission enforcement.
- Resetting filters must also reset page index.
- Export usually uses current filter snapshot, not live table state.

Verification:
- Build & typecheck pass
- Empty state renders correctly
- Filter reset also resets page index
- Bulk actions respect permission, not just visibility

和"技术百科"的区别：它知道什么时候触发，告诉 Claude 先看什么，把项目里高信号的坑写出来了。

五、推荐模板

md 复制代码

# [Skill Name]

When to use:
- ...

Goals:
- ...

Workflow:
1. ...
2. ...
3. ...

Gotchas:
- ...

Verification:
- ...

When to use 防止触发模糊；Goals 防止只堆知识没有方向；Workflow 防止只讲原则不讲路径；Gotchas 防止没有高信号内容；Verification 防止只讲实现不讲收口。

文件落在 .claude/skills/<skill-name>/SKILL.md。

六、Skills 和 Commands 的关系

Command 把高频动作做成稳定入口（/plan、/tdd、/verify、/review）。Skill 在某类任务里给 Claude 一套方法论和坑点（admin-table-workflow、permission-review）。

可以组合使用：/review 作为入口，permission-review 作为这个场景下的具体方法论。Command 让入口固定，Skill 让执行路径固定。

七、最推荐先写的 5 个 Skills

不要一口气写十几个：

bugfix-workflow --- 把 Claude 从"先解释后实现"拉回"先复现再修"
admin-table-workflow --- 中后台最高频场景，非常容易藏坑
permission-review --- 最容易"表面没问题，边界错了"的地方
async-export-workflow --- 特别容易被 Claude 想当然地写成同步下载
audit-log-debug --- 路径长、跨前后端、适合固定排查套路

每个 skill 先只写 When to use / Workflow / Gotchas，不要一上来就写成百科全书。

八、从 Session 到 Skill：让系统持续学习

写好第一批 skills 之后，系统怎么越用越好？答案不是"自学习"魔法，而是一条朴素的升级路径：

text 复制代码

Session Summary → 保存当前任务最关键的状态
Memory → 保存跨任务长期有效的项目规律
Skill → 保存"某类问题怎么做"的方法论

具体例子：今天修"用户导出卡死"的问题，发现了三件事。发现 A（这次根因是轮询状态没在失败态超时退出）→ 留在 session summary。发现 B（项目里所有导出功能都是异步任务模式）→ 升级到 memory。发现 C（总结出了一套稳定的导出链路排查流程）→ 升级成 async-export-workflow skill。

每次总结经验时先问："这是一条当前任务状态、长期项目规律，还是任务方法论？"

九、什么经验值得升级成 Skill

一条经验只有同时满足三个条件才值得升级：

重复出现。 已经遇到三次以上。

改变默认路径。 不只是"小心一点"，而是明确改变推进顺序。

明确可复用。 未来你真的愿意再次显式调用它。

不满足的先放在 session summary 或 memory 里。系统的成熟不是资产越来越多，而是资产越来越有区分度。

固定升级流程：

text 复制代码

任务结束 → 写 session summary → 回看 summary
  → 把跨任务长期有效的规律提到 memory
  → 把会改变默认路径的方法升级成 skill

十、Skill 什么时候该重构

很多人写 skill 的方式是先写一版、遇到坑就补一条。短期顺手，但一段时间后 skill 变成补丁堆。

如果出现以下三种现象中的两种就该重构：触发条件开始模糊（边界可能太大了）；gotchas 越堆越多已经跨了多个场景（应该拆成两个 skill）；Claude 还是经常在这个任务里重复犯错（不是信息不够，而是结构不对）。

Skill 不是写完就结束，它也会演化。

十一、本章交付

Skill 质量检查表： 触发场景是否明确？有没有改变 Claude 的默认做事路径？是不是主要在讲方法而不是重复常识？有没有高信号 gotchas？边界是否够清晰？有没有指出如何验证？

经验升级判断表：

经验类型	该放哪
当次任务做到哪、下一步做什么	Session Summary
项目长期规律、边界、常见坑	Memory
某类任务的可复用方法论	Skill

最小落地动作： 先建 .claude/skills/，只起 3-5 个最高频目录；每个 skill 先只写 When to use / Workflow / Gotchas；每次长任务结束先写 session summary；每周回看一次 summary，只把重复出现、会改变默认路径的经验升 skill。

十二、小结

Skill 不是"我知道很多东西"的文档，而是"Claude 在某类任务里应该怎么走"的方法论包。学习不是把更多东西存起来，而是把值得反复执行的方法从任务里提炼出来。

下一章进入并行能力：Subagent、Background Task、Task System------把思考分出去、把等待分出去、把推进结构化。