代码语言

知识点思维导图

21 个知识节点

参考资料

Skill（12） - Skill 分享、版本与演进

读完后，你应能完成以下任务：

绘制“Skill（12） - Skill 分享、版本与演进 / 持续演进：技能也要迭代”的关键对象与数据流，解释“收集反馈：用的人觉得「触发不准」「产出漏了点」，就是迭代信号。 -> 小步改进：一次改一处（第 10 章纪律），改完跑测试用例。 -> 记录变更：重要修改在提交信息或 README 里写一句「为什么改」，方便回溯。 -> 定期回顾：技能多了之后，定期看看有没有「职责重叠该合并」或「太大该拆分」的。”，并用源码位置、日志或 Trace 标注证据。

为“Skill（12） - Skill 分享、版本与演进 / 团队落地的一套简单方案”设计正常与异常输入，验证“建一个共享目录：在项目仓库的 .claude/skills/ 下放团队公认的技能。 -> 定个简单规范：命名用小写连字符、每个技能附测试用例、改动走 PR review。 -> 从一个高频痛点起步：选团队最常重复的一件事（如代码审查、写周报）做成第一个技能，让大家尝到甜头。 -> 鼓励贡献：谁有好用的个人技能，整理一下提进共享目录。”，输出首个偏差位置与回归测试结果。

实现“Skill（12） - Skill 分享、版本与演进 / 常见错误”的最小代码或配置，检验“❌ 全用个人级，团队各搞各的：同一个技能十个人写十遍，标准不统一。”，输出命令、结果与 Diff，并说明不适用边界。

一、先建立全局：Skill 分享、版本与演进是什么？

理解“Skill 分享、版本与演进”，先要把标题中的对象放进同一条处理链：它接收什么输入，经过哪些状态变化，最终用什么证据判断结果。下表不另造概念，只把作者正文已经解释的章节按依赖顺序连起来。

“Skill 分享、版本与演进”的第一个核心判断是：收集反馈：用的人觉得「触发不准」「产出漏了点」，就是迭代信号。 -> 小步改进：一次改一处（第 10 章纪律），改完跑测试用例。 -> 记录变更：重要修改在提交信息或 README 里写一句「为什么改」，方便回溯。 -> 定期回顾：技能多了之后，定期看看有没有「职责重叠该合并」或「太大该拆分」的。。先弄清这个判断中的对象和输入输出，后面的实现、故障和验收才有共同语境。

顺序	章节	读完本节应抓住的结论
1	持续演进：技能也要迭代	收集反馈：用的人觉得「触发不准」「产出漏了点」，就是迭代信号。 -> 小步改进：一次改一处（第 10 章纪律），改完跑测试用例。 -> 记录变更：重要修改在提交信息或 README 里写一句「为什么改」，方便回溯。 -> 定期回顾：技能多了之后，定期看看有没有「职责重叠该合并」或「太大该拆分」的。
2	团队落地的一套简单方案	建一个共享目录：在项目仓库的 .claude/skills/ 下放团队公认的技能。 -> 定个简单规范：命名用小写连字符、每个技能附测试用例、改动走 PR review。 -> 从一个高频痛点起步：选团队最常重复的一件事（如代码审查、写周报）做成第一个技能，让大家尝到甜头。 -> 鼓励贡献：谁有好用的个人技能，整理一下提进共享目录。
3	常见错误	❌ 全用个人级，团队各搞各的：同一个技能十个人写十遍，标准不统一。
4	最佳实践	按作用域选位置：个人工具放个人级，团队标准放项目级（进 Git 仓库）。
5	🎓 写在最后：你已经走完全程	入门：搞懂了 Skill 是什么、亲手跑通了第一个、看懂了目录结构。
6	技能不是写完就完事	技能不是写完就完事，它会随业务变化。

1.1 核心对象之间怎样衔接

flowchart LR
  S1["持续演进：技能也要迭代"] --> S2
  S2["团队落地的一套简单方案"] --> S3
  S3["常见错误"] --> S4
  S4["最佳实践"] --> S5
  S5["🎓 写在最后：你已经走完全程"]

这张图只表达本文的讲解顺序，不替代正文机制。判断“Skill 分享、版本与演进”是否真正掌握，需要能从最后一个结果沿图回到前面每个章节的输入、状态变化和证据。

1.2 再看失败：问题最早会出现在哪一步？

在“Skill 分享、版本与演进”的对象和顺序已经明确后，再看可观察的失败：版本不明、配置漂移、健康检查失真或数据不兼容。定位时不从最后一条错误猜原因，而是沿上图找第一个偏离正文结论的节点。

二、持续演进：技能也要迭代

技能不是写完就完事，它会随业务变化。建立一个轻量的迭代习惯：

收集反馈：用的人觉得「触发不准」「产出漏了点」，就是迭代信号。
小步改进：一次改一处（第 10 章纪律），改完跑测试用例。
记录变更：重要修改在提交信息或 README 里写一句「为什么改」，方便回溯。
定期回顾：技能多了之后，定期看看有没有「职责重叠该合并」或「太大该拆分」的。

把技能当成「活的文档」：它和业务一起成长，越用越准、越用越好。

三、团队落地的一套简单方案

如果你想在团队推行技能，这套流程最省心：

建一个共享目录：在项目仓库的 .claude/skills/ 下放团队公认的技能。
定个简单规范：命名用小写连字符、每个技能附测试用例、改动走 PR review。
从一个高频痛点起步：选团队最常重复的一件事（如代码审查、写周报）做成第一个技能，让大家尝到甜头。
鼓励贡献：谁有好用的个人技能，整理一下提进共享目录。
定期清理：淘汰没人用的、合并重复的，保持技能集精简。

四、常见错误

❌ 全用个人级，团队各搞各的：同一个技能十个人写十遍，标准不统一。该共享的放项目级。
❌ 技能进了仓库却没文档：新人看不懂、不敢改，慢慢变成没人维护的黑盒。
❌ 从不迭代：业务变了技能没跟上，触发不准还在用，越用越糟。
❌ 改技能不走 review：团队共享的技能被人随手改坏，影响所有人。
❌ 技能越堆越多不清理：重复、过时的技能互相干扰，触发开始混乱。

五、最佳实践

按作用域选位置：个人工具放个人级，团队标准放项目级（进 Git 仓库）。
技能自带文档：description 清晰 + 正文首句说职责 + 必要时附 README。
改动走 PR：团队共享技能和代码一样 review，防止被改坏。
从高频痛点起步推行，让团队先尝到甜头再铺开。
定期回顾：合并重复、拆分过大、淘汰过时。

六、🎓 写在最后：你已经走完全程

回头看看你学到了什么：

入门：搞懂了 Skill 是什么、亲手跑通了第一个、看懂了目录结构。
进阶：吃透了 frontmatter、description 触发机制、渐进式披露，会配资源和脚本。
实战：做了一个完整的代码审查技能，会调试测试，掌握了最佳实践，能组织分享。

现在，你完全有能力独立设计、编写、调试并分享一个真正可用的 Skill了。

最后送你一句话：

最好的学习方式，是现在就去把你今天重复做的某件事，做成一个技能。

打开终端，mkdir ~/.claude/skills/我的第一个技能，开始吧。 🚀

七、动手实践：12 章 Demo · 团队技能库范例

演示如何把技能放进项目仓库、共享给整个团队。

7.1 结构

团队技能库示例/
└── .claude/
    └── skills/                 # 团队共享技能目录（提交进 Git）
        ├── README.md           # 团队规范 + 使用/贡献指南
        ├── code-review/
        │   └── SKILL.md
        └── weekly-report/
            └── SKILL.md

7.2 看点

技能放在项目的 .claude/skills/ 里，而不是个人的 ~/.claude/skills/。区别：
- 个人级：只有你能用，跟着你的机器走。
- 项目级：随仓库分发，团队所有人 git pull 就有了。
目录里有 README.md 写明团队规范——这让技能库可维护、新人能上手。
每个技能依然遵循前面所有章节的原则：单一职责、规范 frontmatter、清晰 description。

7.3 怎么用到你的真实项目

# 在你的项目根目录下创建技能目录
mkdir -p .claude/skills

# 把技能放进去，然后提交
git add .claude/skills
git commit -m "feat: 添加团队共享技能 code-review 和 weekly-report"

队友 git pull 后，这些技能在该项目里自动可用。

7.4 你会收获什么

看懂个人级 vs 项目级的实际差异。
一套可直接复制到真实项目的团队技能库结构和规范。

八、动手验证：先跑通 Skill 分享、版本与演进，再改变一个变量

前面的章节已经建立问题、概念和机制。现在把“Skill 分享、版本与演进”放进同一套基线中运行；本节不再引入新术语，只验证前文结论能否被复现。

8.1 基线与候选只允许一个变量不同

验证“Skill 分享、版本与演进”时，先固定制品、配置、数据版本、健康检查、灰度与回滚条件。候选方案只能改变本次要验证的变量；如果同时更换数据、依赖和配置，即使结果改善，也不能知道是哪一项产生作用。

执行“Skill 分享、版本与演进”时，动作是：按测试、影子、灰度、全量发布并执行兼容检查。原始结果不能只保留截图或汇总分数，必须同步保存：制品摘要、部署事件、错误率、业务指标、回滚记录，使下一次复查可以在同一输入上重放。

实验要素	本文要求
固定条件	制品、配置、数据版本、健康检查、灰度与回滚条件
唯一变量	本次候选方案与基线之间的一项明确差异
原始证据	制品摘要、部署事件、错误率、业务指标、回滚记录
通过阈值	版本可追溯，灰度不劣于基线，回滚路径已验证
立即停止	版本不明、配置漂移、健康检查失真或数据不兼容

8.2 执行前先排除不可比较条件

“Skill 分享、版本与演进”开始前先确认下面四项；任一项不成立，都应先修复实验条件，而不是解释结果。

基线能够在“Skill 分享、版本与演进”的当前环境重复运行。
候选只改变一个与“Skill 分享、版本与演进”结论直接相关的条件。
“Skill 分享、版本与演进”的基线和候选使用同一批输入、同一版本依赖与同一通过阈值。
“Skill 分享、版本与演进”的原始输出和失败现场不会被重试、格式化或汇总覆盖。

8.3 执行后先核对证据完整性

结果出来后先检查证据，再讨论“Skill 分享、版本与演进”是否通过。缺少中间状态时，最终输出只能说明现象，不能证明机制。

检查项	当前文章的判定
输入可追溯	制品、配置、数据版本、健康检查、灰度与回滚条件
过程可回放	按测试、影子、灰度、全量发布并执行兼容检查
结果可审计	制品摘要、部署事件、错误率、业务指标、回滚记录

“Skill 分享、版本与演进”的一次合格基线对照按以下顺序执行：

保存“Skill 分享、版本与演进”基线版本及输入摘要，确认基线本身可以重复运行。
写下“Skill 分享、版本与演进”候选方案唯一变化的变量，以及它预期影响的指标。
在同一环境执行“Skill 分享、版本与演进”：按测试、影子、灰度、全量发布并执行兼容检查。
为“Skill 分享、版本与演进”保存：制品摘要、部署事件、错误率、业务指标、回滚记录。
使用“Skill 分享、版本与演进”预登记条件判断：版本可追溯，灰度不劣于基线，回滚路径已验证。
如果“Skill 分享、版本与演进”未通过，不修改第二个变量，先恢复基线并保留失败现场。

九、用一张矩阵验证 Skill 分享、版本与演进的关键结论

矩阵按正文顺序列出“Skill 分享、版本与演进”的结论。一次实验只选择一行，只改变这一行对应的条件；不要把多行合并成一个无法归因的大实验。

正文章节	已解释的结论	本轮唯一变量	必须保存的证据
持续演进：技能也要迭代	收集反馈：用的人觉得「触发不准」「产出漏了点」，就是迭代信号。 -> 小步改进：一次改一处（第 10 章纪律），改完跑测试用例。 -> 记录变更：重要修改在提交信息或 README 里写一句「为什么改」，方便回溯。 -> 定期回顾：技能多了之后，定期看看有没有「职责重叠该合并」或「太大该拆分」的。	只改变与“持续演进：技能也要迭代”相关的条件	制品摘要、部署事件、错误率、业务指标、回滚记录
团队落地的一套简单方案	建一个共享目录：在项目仓库的 .claude/skills/ 下放团队公认的技能。 -> 定个简单规范：命名用小写连字符、每个技能附测试用例、改动走 PR review。 -> 从一个高频痛点起步：选团队最常重复的一件事（如代码审查、写周报）做成第一个技能，让大家尝到甜头。 -> 鼓励贡献：谁有好用的个人技能，整理一下提进共享目录。	只改变与“团队落地的一套简单方案”相关的条件	制品摘要、部署事件、错误率、业务指标、回滚记录
常见错误	❌ 全用个人级，团队各搞各的：同一个技能十个人写十遍，标准不统一。	只改变与“常见错误”相关的条件	制品摘要、部署事件、错误率、业务指标、回滚记录
最佳实践	按作用域选位置：个人工具放个人级，团队标准放项目级（进 Git 仓库）。	只改变与“最佳实践”相关的条件	制品摘要、部署事件、错误率、业务指标、回滚记录
🎓 写在最后：你已经走完全程	入门：搞懂了 Skill 是什么、亲手跑通了第一个、看懂了目录结构。	只改变与“🎓 写在最后：你已经走完全程”相关的条件	制品摘要、部署事件、错误率、业务指标、回滚记录
技能不是写完就完事	技能不是写完就完事，它会随业务变化。	只改变与“技能不是写完就完事”相关的条件	制品摘要、部署事件、错误率、业务指标、回滚记录

9.1 记录本次实际实验

下面的记录用于“Skill 分享、版本与演进”当前这一次实验，不是第二套知识目录。先从矩阵选择一个章节，再填写实际值；没有填写的字段表示尚未验证。

topic: "Skill 分享、版本与演进"
selected_chapter: required
claim_from_article: required
baseline_version: required
changed_condition: exactly_one
execution: "按测试、影子、灰度、全量发布并执行兼容检查"
evidence: "制品摘要、部署事件、错误率、业务指标、回滚记录"
pass_when: "版本可追溯，灰度不劣于基线，回滚路径已验证"
stop_when: "版本不明、配置漂移、健康检查失真或数据不兼容"
observed_result: required
first_deviation: null_or_evidence
recovery_replay: required_after_failure

9.2 边界实验必须证明能够停止和恢复

成功路径只能证明“Skill 分享、版本与演进”在当前样本上工作，不能证明它可以进入生产。边界实验需要主动制造：版本不明、配置漂移、健康检查失真或数据不兼容，并观察系统是否在产生不可逆副作用前停止。

场景	只改变什么	应保存什么	通过标准
正常路径	使用已知有效输入	制品摘要、部署事件、错误率、业务指标、回滚记录	版本可追溯，灰度不劣于基线，回滚路径已验证
边界路径	把一个输入推进到约束临界值	临界值前后的输出与指标	不静默降级，不把部分结果冒充成功
明确失败	注入：版本不明、配置漂移、健康检查失真或数据不兼容	原始错误、首个异常阶段和最终状态	失败被正确分类且没有扩大副作用
恢复重放	执行：停止扩量，回滚制品与配置，数据采用前向修复	原失败样本的复测证据	原样本恢复，正常样本没有回归

恢复动作不是简单重启。对于“Skill 分享、版本与演进”，第一步是：停止扩量，回滚制品与配置，数据采用前向修复。完成后使用原始失败样本复测；只验证一个新样本成功，不能证明触发条件已经消失。

“Skill 分享、版本与演进”边界实验结束后，应把正常、临界、失败和恢复四类记录放在同一个运行批次中。这样才能区分“候选方案真的修复问题”和“环境变化让问题暂时没有出现”。

十、Skill 分享、版本与演进的结果解释

解释“Skill 分享、版本与演进”实验时先看首个偏差，而不是最后一条错误。最后的异常通常只是上游状态错误的结果；从末端反推容易误把症状当根因。

观察结果	可以支持的判断	下一步
主链路没有达到预期	版本不明、配置漂移、健康检查失真或数据不兼容	先执行：停止扩量，回滚制品与配置，数据采用前向修复
异常链路无法恢复	版本不明、配置漂移、健康检查失真或数据不兼容	先执行：停止扩量，回滚制品与配置，数据采用前向修复
新样本成功但原样本仍失败	修复没有覆盖原始触发条件	固定原失败输入，恢复基线后重新比较
指标改善但证据无法回链	数据、版本或中间状态没有固定	暂停发布，补齐可追溯记录后重跑

“Skill 分享、版本与演进”只有同时满足“版本可追溯，灰度不劣于基线，回滚路径已验证”，并且没有出现“版本不明、配置漂移、健康检查失真或数据不兼容”，才可以认为主链路通过。这里的“通过”只对当前固定版本、样本和环境有效，不能外推到尚未测试的容量、权限或数据分布。

如果“Skill 分享、版本与演进”候选方案与基线差异很小，先检查证据分辨率是否足够；如果差异很大，先排除数据泄漏、环境漂移和版本不一致。两种情况都不能只看一个汇总均值，需要回到逐样本输出和中间状态。

“Skill 分享、版本与演进”故障定位完成后，记录“现象、首个偏差、根因、改动、原样本复测”五项。缺少原样本复测时，只能标记为待观察，不能标记为已解决。

十一、Skill 分享、版本与演进的发布判断

发布判断需要把“Skill 分享、版本与演进”的质量、失败边界和恢复能力放在同一份记录中。以下任一条件缺失，都应停止扩量，而不是用“基本正常”替代证据。

“Skill 分享、版本与演进”的基线与候选只存在一个计划内变量。
“Skill 分享、版本与演进”的输入、代码、依赖、配置和数据版本可以追溯。
“Skill 分享、版本与演进”的正常、临界、失败和恢复样本使用同一套断言。
“Skill 分享、版本与演进”的原始输出、中间状态和失败现场已经保留。
“Skill 分享、版本与演进”的日志、Trace、截图和测试数据已经脱敏。
“Skill 分享、版本与演进”的停止条件、负责人和回滚入口已经演练。
“Skill 分享、版本与演进”尚未覆盖的输入、权限、容量和外部依赖已经登记。

最终记录至少包含基线版本、唯一变量、原始证据、首个偏差、恢复复测和发布责任人。没有参与本次修改的人如果不能据此重放“Skill 分享、版本与演进”的判断，就不能发布。

十二、总结

作用域：个人 Skill 服务个人习惯，项目级 Skill 随仓库分发并接受团队约束，不能把机器私有路径写进共享能力。
版本演进：根据触发错误和产出缺口小步修改，每次只改变一个可验证行为，并在提交或变更记录中说明原因。
质量门禁：共享 Skill 的 description、正文、脚本和测试用例一起走 PR，成功、边界和失败样例都通过后才能合并。
生命周期：定期统计使用情况，合并职责重复项、拆分过大项并删除过时项，避免多个 Skill 争抢同一触发场景。