Claude Code Harness ：Skills 从编写到演化

在尝试为 Claude 写 skill 时很多人都会遇到相同的痛点：

• 触发条件模糊——不知道什么时候让 Claude 调用这个 skill。
• 内容过长、缺乏聚焦——像百科全书一样写，导致实际使用时被忽略。
• 无法持续迭代——一次性写完后就不再更新，变成碎片堆积。
• 缺少验证机制——不知道怎么确认 skill 是否真正改变了行为。
• 与命令耦合不清晰——难以判断何时用 Skill，何时用 Command。

下面的章节将逐步解决这些痛点，并给出实战可落地的模板和升级流程。

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

痛点：把所有知识都塞进去，却没有改变实际行为。

各层分工这方面，CUSTOMER.md 负责项目级总说明；Rules 负责长期约束；Memory 负责长期项目经验；其实，Skill 负责某类任务怎么做。

A skill 的目标不是“把你知道的都告诉 Claude”，而是在某类任务里改变 Claude 的默认方法——把它最容易走错的方向重新拉回正确方法。

二、好 Skill 的三个主要要素

• 明确触发场景。

*痛点*：触发条件不清导致 skill 被忽略或误调用。例子的观点是，

• 坏例："高级前端开发常用方法"
• 好例："用于中后台列表页筛选、分页、排序、批量操作相关功能的实现与审查。"
• 改变默认行为。不过，

*痛点*：只是再说“保持代码整洁”。没有真正影响流程，好例子告诉 Claude 在此任务里先做什么再做什么哪些看似顺手却不该做，还有完成判定标准。

• 高信号 Gotchas。

*痛点*：忽略细节导致反复出现错误。常见 Gotcha 如：

• "all"不是有效值，而是“不传此字段”。
• "菜单隐藏"≠权限校验。
• "导出接口"是异步 job，而非同步下载。

三、反例：坏 skill 长什么样？不过，

# 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 示例

# 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 wher URL,local state,or server params drive table state.
3. Lock current behavior with targeted tests where feasible.
4. Make smallest possible change to filters / sort / pagination flow.
5. Verify empty state。reset behavior,and permission-gated bulk actions.
Gotchas:
- `"all"` often means omit filter param,not send `"all"` to backend.
- Bulk action visibility is not 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 看什么把项目里高信号坑写出来了。

五、推荐模板

#
When to use:
- ...
从Goals来看。- ...
Workflow:
- ...
Gotchas:
- ...
Verification:
- ... 

至于*解释*，

• No “When to use”: 避免触发模糊； 话说回来，
• No “Goals”: 防止只堆知识无方向；
• No “Workflow”: 避免只讲原则不讲方法；
• No “Gotchas”: 避免没有高信号内容；
• No “Verification”: 防止只讲实现不讲收口。
• .claude/skills//SKILL.md 保存位置。

六、Skills 与 Commands 的关系

a) Command 把高频动作做成稳定入口。b) Skill 在某类任务里给 Claude 一套方法论和坑点。其实，至于组合使用示例，先 /review。再调用 permission-review。Command 固定入口，Skill 固定执行方法。

七、最推荐先写的 Skills

• /bugfix-workflow: 把 Claude 从“先解释后实现”拉回“先复现再修”。
• /admin-table-workflow: 中后台最高频场景，比较容易藏坑。
• /permission-review: 最容易出现“表面没问题，边界错了”的情况。
• /async-export-workflow: 常被误认为同步下载。老实说，
• /audit-log-debug: 方法长跨前后端。适合固定排查套路，每个 skill 初始只写 When / Workflow / Gotchas，不要一上来就塞满百科全书式内容。

八、从 Session 到 Skill

*痛点*这方面。程序使用后不会自动学习，只能靠人工并拆解为新的资产。

Session Summary → 保存当前任务最关键状态 → 保存跨任务长期规律 → 保存“某类问题怎么做”的方法论

说到举例说明，

* 当天修复「使用者导出卡死」： * A>> session summary * B>> memory * C>> async-export-workflow skill * 每次经验前问：“这是当前任务状态？还是长期规律，还是方法论？其实，” * 确认满足三个条件才升级为 Skill。* 不满足者保存在 session summary 或 memory。* 程序成熟不是资产越多，而是资产越有区分度。* 升级流程简化： `Task finished → Session summary → Review summary → Memory update → Skill upgrade` * h4 “何时重构？” **重构判据**： | 判据 | 描述 | 是否需要重构 | |------|------|--------------| | **触发模糊** | 边界太大或无法区分具体情境 | ✔️ | | **Gotcha 跨场景** | 同一条 gotcha 用于多个 unrelated 场景 | ✔️ | | **频繁错误** | Claude 在此技能下仍重复犯错 | ✔️ | **重构步骤**： 1. 划分更细粒度子技能或拆分为不同领域；2. 明确每个子技能的触发边界；3. 加入更多验证步骤，---

九、本章交付**

Skill 检查清单
触发场景是否明确？	是否改变默认方法？	主要内容是否方法论而非常识？	有没有高信号 Gotcha？	边界是否足够清晰？
Please fill out above columns based on your skill draft.
经验升级判断表格
经验类型	放置位置	评估标准	建议动作

MOTIVATION TIP – 小结行动项：

• Create .claude/skills folder – only highest‑frequency categories initially.
• Add minimal sections ) for each new skill.
• Aim for one new skill per week after each long task.
• The first iteration focuses on When→Workflow→Gotchas.
• A regular review cadence ensures only repeatable & path‑altering experiences become skills. ---

  十、小结—从理论到实践**

  Bare‑bones lessons learned:

  - Skills are method packages that alter default paths within specific tasks. - Templates keep you from writing generic encyclopedias. - Separate concerns 娱乐ween Commands and Skills . - Continuous iteration comes from mapping sessions→memory→skills systematically. - Use clear verification steps so you know when a change truly worked. - Don’t let skills become static relics—refactor when triggers blur or gotchas spread across scenarios. - Remember that maturity is measured by clarity and reuse potential rar than sheer volume of assets.

  MIGRATION TO NEXT CHAPTERS – Parallelism Roadmap : Subagent + Background Task + Task System — think about delegating thinking and waiting while structuring progress step by step.