从prompt 到可复用 Skill：我花了 30 天把个人经验变成 AI 能继承的知识

那是我第二十三次向 AI 解释同一件事。

不是因为 AI 忘了。每次都是新的会话，新的上下文，新的起点。AI 没有记忆，所以它不存在"忘了"——它只是从来没有被允许记住。

那件事是这样的：我们的项目有一个奇怪的约定，所有涉及用户权限的函数，必须在函数名里带 _with_permission 后缀，而不是用装饰器。不是最优雅的设计，是历史遗留的。三年前某个架构决定的化石，嵌在我们整个代码库的命名规范里。每个新人都需要被告知这件事，每次 code review 都会提到它，每次我用 AI 处理权限相关的代码，我都要在 prompt 里专门说一遍。

第二十三次说完，我停下来想了一秒钟。

我计算了一下：二十三次，每次大概花 20 秒解释，加上 AI 重新理解上下文的那些来回，每次任务平均多花了 3 分钟。二十三次就是 69 分钟。将近一个工作上午。

这 69 分钟，我什么都没生产。我只是在重复地教一个没有记忆的工具，同一句话，二十三次。

有一种职业，每天也在面对"没有记忆"的问题，但他们几百年前就找到了解法。

那就是厨师。

一、老厨师的批注本

任何一家有传承的餐厅，后厨都会有一本东西。

表面上它是菜谱，但菜谱不是它最值钱的部分。菜谱本身可以复刻，食材配比可以测量，火候可以计时。最值钱的是菜谱旁边那些手写的批注——用圆珠笔写在页边，有时候因为纸太小而写到了菜谱背面：

这个步骤夏天要少放两成酱油，因为高温会让发酵更快。

用这个牌子的花椒会太麻，换另一家的。

翻炒时间不是三分钟，是锅边开始冒白烟再等四十五秒。

这些批注，不是菜谱本身。菜谱是知识，批注是经验。

知识可以从书上学，经验只能从做错里来。每一条批注背后，都是某一次做坏了，然后那个厨师在那一刻想明白了为什么，然后他做的第一件事不是重新做一遍，而是拿起笔写下来。

这个写的动作，是整个传承系统里最关键的一步。

不写，经验留在那个厨师的脑子里，他退休了，经验消失了。

写了，经验进入了一个可以被继承的载体，新来的厨师不需要重新踩同样的坑，不需要被师傅一遍遍口头告知，打开菜谱，批注在那里。

我们用 AI 的方式，大多数时候相当于在没有批注的菜谱前给厨师念菜谱。我们把经验留在了对话框里，一个会话结束，那些经验就消失了，下次从头来过。

Skill，是 AI 的批注本。不是菜谱本身，是那些让菜谱变得可靠的边缘书写。

二、prompt 和 Skill 的本质差距

在我真正坐下来系统地做 Skill 之前，我想先说清楚这两件事为什么在本质上不一样——不是程度的不同，而是目的的不同。

一个 prompt 是写给当前这次任务的。它包含这次任务的背景、要求、限制。它的生命周期是这一次对话。对话结束，它消失。

一个 Skill 是写给所有未来任务的。它包含的不是这次任务的要求，而是这类任务永远成立的约束和经验。它的生命周期是项目的生命周期，甚至是更长。

用另一个比喻来说：prompt 是今天早上你给外卖员的地址，每次点餐都要重新打一遍。Skill 是你家门口的门牌号，装上去一次，所有人都能找到你。

但这个比喻还不够准确，因为 Skill 比门牌号更复杂。

门牌号是静态的，Skill 是动态生长的。每一次 Loop 运行，每一次 AI 犯了一个新的错，每一次你发现了一个新的约束需要被固化——Skill 都会更新一次，长出新的内容。

一个存在了半年的 Skill 文件，和它刚建立时的版本，可能已经大不相同。但每一次修改背后，都是一次真实发生的、值得被记住的事情。

这就是为什么 Skill 的价值是复利式的，而 prompt 的价值是线性的，甚至是一次性的。

三、我的第一个 Skill 不是设计出来的，是从一次失败里爬出来的

2026 年 5 月中旬的某个星期三，我让一个 Loop 帮我给一批函数补充单元测试。

任务本身不复杂，我给了清晰的要求，Loop 跑了三轮，返回了一批测试文件。

我做了一件我那段时间养成的习惯：不只看测试有没有通过，而是把 AI 写的测试代码打开读一遍。

读到第四个测试函数的时候，我停下来了。

Python

def test_get_user_permissions():
    mock_user = MagicMock()
    mock_user.id = "user_123"

    result = get_user_permissions(mock_user)

    # AI 写的断言
    assert result is not None
    assert isinstance(result, list)

两个断言：结果不是 None，结果是 list 类型。

这两个断言从技术上说是正确的。测试确实通过了。

但这两个断言保护了什么？

它们确认了函数返回了某个 list，但没有验证那个 list 里有什么，没有验证权限是否正确，没有验证在用户 ID 不存在时函数的行为，没有验证权限列表的格式是否符合预期。

这是一个通过了但几乎没有价值的测试。如果 get_user_permissions 有一天开始返回空 list，或者返回错误的权限，这个测试不会失败——因为它测的不是"权限是否正确"，它测的是"函数有没有返回一个 list"。

我把 Loop 的日志翻出来看了一遍，想弄清楚为什么 AI 会写这种断言。

答案其实很简单：我没有告诉它不能这样写。

我的任务描述是："为这些函数编写单元测试"。这个指令是完全合法的，AI 完全正确地理解了它，然后用了效率最高的方式完成了它——写出能通过的测试。

能通过不等于有价值。这两件事在这里不是同一件事，但我没有告诉 AI 它们不是。

我花了一个小时检查那批测试，发现大约 40% 的断言是这种"形式上正确、实质上没有防护能力"的类型。

那天晚上我写了第一个 Skill 文件。不是因为我设计了一个 Skill 系统，而是因为我意识到，如果我不把这件事写下来，下次用 AI 写测试，它还会这么做，我还会花一个小时检查，然后这段历史会重演。

这是第一个 Skill 文件最早的样子：

Markdown

# SKILL: unit_test_quality
创建日期：2026-05-14
触发场景：所有"编写单元测试"类任务

## 这个 Skill 的来源
AI 倾向于写"能通过"的测试，而不是"有保护价值"的测试。
核心表现：使用 `is not None` 和 `isinstance` 这类极弱的断言。

## 必须遵守的断言标准
- 断言必须验证具体的返回值，不只是类型
- 断言必须覆盖至少一个边界条件（空输入、无效参数、异常情况）
- 禁止使用以下弱断言（除非有明确说明原因）：
  × assert result is not None
  × assert isinstance(result, SomeType)
  × assert len(result) > 0
- 鼓励使用的断言类型：
  ✓ assert result == expected_value
  ✓ assert result["key"] == "specific_value"
  ✓ with pytest.raises(SpecificException): ...

## 示例：弱测试 vs 强测试

# ❌ 弱测试（不应该这样写）
def test_get_user_permissions():
    result = get_user_permissions(user)
    assert result is not None
    assert isinstance(result, list)

# ✅ 强测试（应该这样写）
def test_get_user_permissions_returns_correct_roles():
    user = User(id="user_123", role="editor")
    result = get_user_permissions(user)
    assert "edit_content" in result
    assert "publish_content" not in result  # editor 不能发布

def test_get_user_permissions_raises_for_unknown_user():
    with pytest.raises(UserNotFoundError):
        get_user_permissions(User(id="nonexistent"))

不长。写下来花了 20 分钟。

但它包含的是那一个小时检查的浓缩，以及那个我以后不想再花的一小时的预付款。

四、什么让一个 Skill 真正有用

写完第一个 Skill，我开始思考它的结构。不是为了让它看起来更整齐，而是因为我意识到一个 Skill 需要回答六个问题，缺少任何一个，它的效果都会打折扣。

第一个问题：这个 Skill 适用于什么场景？

Skill 不是全局规则，它是有条件的。unit_test_quality 这个 Skill 适用于"编写测试"类任务，但对"修复 CI 失败"类任务就不一定合适——有时候修 CI 需要快速找到问题根因，这时候测试质量可以临时放宽。

如果 Skill 没有明确的适用边界，它会在不该激活的地方激活，产生干扰。

第二个问题：这个 Skill 需要什么输入？

有些 Skill 是无条件的规则，有些 Skill 需要先拿到某些信息才能工作。比如后来我写的 pr_description Skill，它需要拿到对应的 issue 链接和修改的核心动机，才能生成有价值的 PR 说明。没有这些输入，它只能生成一个格式正确但内容空洞的说明。

第三个问题：执行步骤是什么顺序？

这是最容易被忽略的一个。有些任务，顺序至关重要。

写测试的时候，正确的顺序是：先理解被测函数的预期行为，再分析边界条件，最后写测试代码。如果 AI 直接跳到写测试代码，往往会写出形状正确但覆盖错误的测试。

把顺序写进 Skill，不是在教 AI 怎么思考，而是在告诉它这类任务有一个被验证过有效的思考路径，优先走这条路。

第四个问题：已知坑是什么？

这是 Skill 文件里最值钱的部分，也是最容易被省略的部分。

已知坑不是抽象的警告，不是"注意代码质量"，不是"小心边界条件"。已知坑是非常具体的、在这个项目里已经发生过的、值得被记住的问题。

generate_user_id() 在毫秒级精度下的并发问题，[email protected] 在我们 Node 版本下的序列化 bug，权限函数命名必须带 _with_permission 后缀——这些都是已知坑，它们不是任何通用文档里会出现的东西，它们只存在于这个项目的历史里。

把已知坑写进 Skill，等于把项目的记忆载入到 AI 的上下文里。

第五个问题：有哪些禁止行为？

这个维度和已知坑互补。已知坑是"这里有陷阱，绕开走"，禁止行为是"不管怎么做，这件事不被允许"。

两者的区别：已知坑是 AI 可能误入的地方，禁止行为是 AI 可能主动选择的方向但那个方向不可以走。

第六个问题：完成后应该输出什么？

期望产出是 Skill 的终点定义。没有终点，AI 不知道什么时候可以停，以及停下来应该给你什么。

这六个问题，就是一个完整 Skill 的骨架。

五、一个成熟的 Skill 文件长这个样子

这是我花了三十天迭代出来的 bug_fix Skill，目前是 1.4 版本。

把它完整贴在这里，是因为我认为一个真实的案例，比任何抽象描述都更能说明 Skill 应该是什么样的：

Markdown

# SKILL: bug_fix
版本：1.4
创建日期：2026-04-03
最后更新：2026-06-11
更新原因：新增 legacy/payment 目录保护规则（v1.3 → v1.4）

---

## 适用场景
- 有明确报错信息的 bug 修复
- 有对应 failing test 的 bug 修复
- CI 失败修复
不适用于：需要跨多个模块重构的系统性问题

---

## 需要的输入
- 报错信息或失败测试输出（必填）
- 预期的正确行为描述（必填）
- 相关代码文件路径（可选，有助于缩短定位时间）

---

## 执行步骤（顺序重要）
1. 读报错，形成复现假设，不要急着改代码
2. 先写 failing test，用 pytest 验证能复现问题
   - 这一步确认我们真的理解了问题
3. 最小化地修改代码让 failing test 通过
   - 只改和问题直接相关的地方，不顺便优化
4. 运行完整测试套件（pnpm test:unit），确认无副作用
5. 生成 PR 说明，格式见下方

---

## 已知坑
- generate_user_id() 在测试环境下精度为毫秒级，
  并发调用（两次调用间隔 < 1ms）会产生重复 ID。
  测试用显式 ID，不用 generate_user_id()。

- auth 模块的 session 超时测试依赖真实时钟，
  不接受 mock.patch('time.time')。用 freeze_gun 库。

- payment 模块测试需要特殊环境变量：
  TEST_PAYMENT_GATEWAY=sandbox
  见 .env.test.example，本地跑测试前必须设置。

- HTTP 状态码语义：
  429 = 速率限制（不是 403）
  422 = 参数验证失败（不是 400）

---

## 禁止行为
- 不得 skip 或 xfail 现有测试
- 不得删除、弱化已有断言
- 不得修改 legacy/payment/ 目录（任何修改需独立 PR + 技术负责人审批）
- 不得用 try/except 吞掉错误来"修复"失败
- 不得修改测试来匹配错误的实现（应该修实现）
- 不得在修 bug 的 PR 里顺便重构无关代码

---

## 完成输出
1. 通过的 pytest 输出（复制完整结果，不截取）
2. diff 摘要（修改了哪些文件，每个文件改了什么）
3. PR 说明草稿，包含：
   - 问题描述（一句话）
   - 根本原因（技术层面）
   - 修复方式
   - 如何验证（测试截图或命令）

---

## 版本历史
v1.0 (2026-04-03) - 初始版本
v1.1 (2026-04-18) - 新增 generate_user_id 并发坑
v1.2 (2026-05-07) - 新增 HTTP 状态码语义说明
v1.3 (2026-05-29) - 新增 freeze_gun 要求
v1.4 (2026-06-11) - 新增 legacy/payment 目录保护规则

读这个文件，和读一个项目的 README 或 CONTRIBUTING.md，感觉是不一样的。

README 告诉你这个项目是什么。CONTRIBUTING.md 告诉你应该怎么贡献。这个 Skill 文件告诉你的是：在这个项目里，做这类事情的时候，这些地方有坑，这些事情不能做，做完了长这个样子。

这是一种更贴近"老员工带新员工"的知识传递，而不是"阅读文档"式的知识传递。区别在于，老员工会告诉你"这段代码三年前被改过，有一个你不会从文档里读到的假设"——而文档不会。

六、三十天，十二个 Skill 文件，四百行

我现在的 Skill 库目录长这样：

text

.claude/skills/
├── bug_fix.md           v1.4  (2026-04-03)
├── unit_test_quality.md v1.3  (2026-05-14)
├── pr_description.md    v1.1  (2026-04-22)
├── ci_fix.md            v1.2  (2026-05-20)
├── code_review.md       v1.0  (2026-06-01)
├── dependency_upgrade.md v1.1 (2026-05-15)
├── readme_update.md     v1.0  (2026-06-05)
├── refactor_safe.md     v1.2  (2026-04-29)
├── api_design.md        v1.0  (2026-05-30)
├── error_handling.md    v1.1  (2026-05-08)
├── performance_check.md v1.0  (2026-06-09)
└── naming_conventions.md v2.0 (2026-04-10)

十二个文件，总计 417 行。

建立这十二个 Skill 的过程，没有一个是"坐下来设计"出来的。每一个都是从一次具体的失败、一次重复解释、一次"AI 做了但没做对"里爬出来的。

naming_conventions.md 就是从那个"权限函数命名"的第二十三次开始的。

error_handling.md 是从 AI 连续三次用 try/except: pass 吞掉异常之后写的。

dependency_upgrade.md 是从 AI 升级了一个依赖、破坏了七个下游测试、而我花了一个小时才找到关联关系之后写的。

每一个文件背后，都有一个让我花了不必要的时间的故事。

三十天后，我做了一次统计：

更有意义的统计：

这三十天里，我记录了所有使用了 Skill 的 Loop 任务，和三十天前没有 Skill 时处理类似任务的历史数据做了对比：

有 Skill 的 Loop，平均轮次减少了 48%，成本减少了 44%。

但这两个数字，都不是我认为最重要的数字。

最重要的是这个：

在有 Skill 的任务里，AI 重复犯同一类错误的频率，从 61% 降到了 9%。

61% 对 9%。

这意味着什么？意味着那个"写弱断言"的问题，写进 Skill 之后，在后续的 31 次测试任务里，只出现了 3 次，而不是 19 次。意味着那个权限函数命名的问题，进了 naming_conventions.md 之后，在后续的 27 次代码任务里，出现了 2 次，而不是 16 次。

Skill 不能保证 AI 永远不犯错，但它把系统性的、可预测的错误，变成了偶发的、需要调查的错误。这是一个质变，而不是量变。

七、Skill 的复利，来自一个具体的机制

我想解释清楚，为什么 Skill 的价值是复利式的，而不只是线性的。

没有 Skill 的时候，每次任务的起点是同一个地方：零。AI 不知道项目的历史，不知道已经踩过的坑，不知道已经固化的规范。每次任务，我都在重复地把一部分这些知识灌进 prompt，然后会话结束，灌进去的东西消失，下次再灌。

这是一个没有积累的系统。每次的投入，都是当次消耗完的。

有了 Skill 之后，每次任务的起点不再是零，而是所有之前任务的知识总和。AI 在这次任务里学到的新东西，被写进 Skill，成为下次任务的起点的一部分。

更关键的是，Skill 之间会产生协同。

bug_fix.md 里有"先写 failing test"的步骤要求，unit_test_quality.md 里有"强断言"的标准——当我在做 bug 修复任务的时候，同时加载这两个 Skill，AI 在写 failing test 的时候就会自动应用强断言标准，而不需要我专门提醒。

两个 Skill 叠加，产生了比两个 Skill 单独使用更好的效果。

这就是复利的机制：不只是每个 Skill 随时间变好，而是 Skill 之间的协同随着 Skill 数量的增加而指数增长。

一个合适的比喻是：Skill 像是城市里的基础设施，每一条路本身有价值，但真正的价值来自于路与路之间的连接，来自于整个网络。四条路加一个路口，比四条孤立的路加起来有价值得多。

八、从个人 Skill 到团队知识库——一次意外的传播

六月初，一个同事在处理一个他不熟悉的模块时，问我有没有关于依赖升级的建议。

我把 dependency_upgrade.md 发给了他。

他沉默了一会儿，然后说：里面那条关于 [email protected] 的已知坑，你怎么知道的？

我告诉他，三个月前 AI 帮我升级 axios，升完之后七个测试失败，我花了一个小时找到了这个序列化 bug，然后写进了 Skill。

他说：我上个月也遇到了一模一样的问题，花了两个小时。

这句话让我意识到了一件事：我的 Skill 库是我一个人踩坑的结晶，但坑不是我一个人踩的。同样的 bug，同样的历史，在不同人身上重复发生，但每个人都在用自己的时间重新踩，重新学，然后记在自己的脑子里，然后这段记忆随着人员流动而消失。

这是团队知识最大的浪费方式：大家都知道的事，没有人写下来；大家都踩过的坑，没有人标记出来。

那天下午，我们把这个话题带到了团队会议上。

讨论之后，我们决定把 Skill 库变成团队共享的东西，放进 git 仓库，建立一个简单的贡献机制。

我们设定了三条规则，非常简单：

规则一：遇到需要重复解释的事，写进 Skill，不要只口头说。

每次有人在 code review 里写下超过两次的同一条评论，那条评论背后的规则，应该进 Skill。

规则二：Skill 需要标注"为什么"，不只是"是什么"。

没有上下文的规则，是难以被记住和执行的命令。有了故事的规则，是可以被理解的约定。

Markdown

# ❌ 只有规则，没有故事
不要使用 [email protected]

# ✅ 有规则，也有来源
- [email protected] 在 Node 16+ 下有一个序列化 bug，
  会在某些 POST 请求里静默截断 payload。
  2026-03 在依赖升级时发现，导致 7 个支付相关测试失败。
  锁定版本在 0.x，等待官方修复。

规则三：Skill 是活的，不是档案。

文档会过期，档案不会被更新。Skill 必须有人负责维护，当项目的情况变了，Skill 要跟着变。每个 Skill 文件有一个 owner，这个人负责它的准确性。

实行这三条规则三周后，我们的团队 Skill 库有了 19 个文件，来自 5 个不同成员的贡献。

最意外的收获：两个新入职的同事，在入职第一周就开始有效地使用 AI 处理任务，而他们之所以能做到这一点，不是因为他们特别厉害，而是因为他们加载了项目的 Skill 库，站在了整个团队三个月踩坑经验的肩膀上。

入职第一周，就跳过了前人走过的弯路。

这是知识系统最重要的价值：不是让人不犯错，而是不犯同样的错。

九、Skill 的三个陷阱，我都踩过

走了三十天，我不想只说好的部分。

有三个问题，如果你打算建立自己的 Skill 系统，值得提前知道。

陷阱一：Skill 写了但没有被加载，等于没写。

这是最常见也最隐蔽的问题。Skill 文件整整齐齐地放在 .claude/skills/ 目录里，但 Loop 启动时没有把它们读进上下文，AI 完全不知道它们的存在。

我大约有两周的时间，以为 Skill 在发挥作用，其实没有。那段时间 AI 还是会犯我以为已经被 Skill 拦住的错，我一直以为是 Skill 写得不够清楚，后来才发现是根本没有被加载。

修复很简单：在 Loop 的启动逻辑里，显式地把相关 Skill 文件读入 system prompt 或者任务描述的前置部分。但这件事需要有意识地去做，不会自动发生。

陷阱二：错误的经验被当成正确的规则写进了 Skill。

五月初，我在处理一个特殊的并发场景时，用了一个变通方案：在测试里加一个 time.sleep(0.01) 来避免时间戳碰撞。这个方案在当时的上下文里是合理的，但它不是通用的最佳实践。

问题是，我太快地把它写进了 Skill，把"在并发测试里可以用 sleep 来避免时间戳碰撞"写成了一条通用规则。

接下来的三周，AI 在几个本来可以用更干净方式处理的地方，都用了这个 sleep 方案。直到有一次代码审查，另一个同事指出这个测试在 CI 里随机失败（因为 CI 服务器有时候比 0.01 秒更慢），我才意识到 Skill 里有一条坏规则在被执行。

Skill 里的规则，不会自动区分"这次有效"和"通用有效"。这个判断需要在写 Skill 的那一刻做。

养成一个习惯：在把任何东西写进 Skill 之前，问自己：这是一条在任何类似情况下都成立的规则，还是一个针对当前特殊情况的变通？如果是后者，它不应该进 Skill，它应该进代码的注释。

陷阱三：Skill 过时了但没有触发更新的机制。

dependency_upgrade.md 里有一条关于 pnpm 版本的建议，那是基于我们当时用的 pnpm 8.x 的行为写的。五月底我们升级到了 pnpm 9.x，那个行为改了，但 Skill 没有更新。

接下来两周，AI 按照 pnpm 8.x 的方式处理了几个依赖升级任务，产生了一些奇怪的、难以定位的问题。

Skill 是活的文档，但活的文档需要有触发更新的机制，不然它会静悄悄地变成过期的指南，而没有人知道它已经过时。

我们的解法是：在每次有重大技术栈变更（依赖升级、框架更新、工具切换）的时候，PR 里加一个检查项：是否需要更新相关 Skill？

这不是完美的解法，但它把更新 Skill 的责任，连接到了一个已经存在的、不容易被跳过的工作流节点上。

十、那二十三次的代价，换来了什么

我在开头说：我花了 69 分钟重复解释同一件事，没有生产任何东西。

三十天后，我重新算了一下这个账。

把那个权限函数命名规则写进 Skill，花了我 15 分钟——写规则、加例子、说明原因。

此后三十天，涉及权限函数的任务里，AI 第一次就用对命名的比例：82%。而在有 Skill 之前，这个比例是 0%——因为 AI 不知道这个约定，我每次都要解释。

保守估计，这 15 分钟节省了我大约 40 分钟的重复解释时间，以及至少 20 分钟的因为命名错误导致的代码审查来回。

15 分钟投入，60 分钟节省，4 倍回报，在第一个月内。

这还是最保守的估计，而且这个回报会随时间持续增加，因为后续每次新任务都在用这条规则，每次都不需要我再解释。

但我认为最重要的不是这个算法，而是这背后的一个更根本的问题：

你的经验，在你工作结束之后，去哪里了？

大多数时候，经验留在脑子里，随着记忆衰退而模糊，随着人员流动而消失。它存在的时候有价值，但它存在的时间有限，而且无法被复制或传递。

Skill 是一种主张：经验值得被固化。不是因为它完美，不是因为它永远成立，而是因为它是真实发生过的、值得被记住的事情，应该比它发生时活得更长。

老厨师退休的时候，那本批注满满的菜谱留在了厨房。新厨师打开它，不只看到了食谱，看到了一个人在这个厨房里工作了几十年所有值得被记住的发现。

那些发现不会因为那个厨师不在了而消失。

它们进入了一个比任何个人都更持久的载体。

这，是知识系统存在的意义。

附：可以直接使用的经验资产

资产一：通用 Skill 模板

Markdown

# SKILL: [skill_name]
版本：1.0
创建日期：YYYY-MM-DD
最后更新：YYYY-MM-DD
更新原因：[这次更新改了什么]

---

## 适用场景
[这个 Skill 在什么任务类型下激活]
[明确写出不适用的场景]

---

## 需要的输入
- [输入一]（必填/可选）
- [输入二]（必填/可选）

---

## 执行步骤
1. [第一步]
2. [第二步]
3. [第三步]
（顺序重要时标注"顺序不可更改"）

---

## 已知坑
- [具体问题描述]
  [发现时间和上下文]
  [正确的处理方式]

---

## 禁止行为
- 不得 [具体禁止的操作]
- 不得 [具体禁止的操作]

---

## 完成输出
[描述任务完成时应该产出什么]
[格式要求]

---

## 版本历史
v1.0 (YYYY-MM-DD) - 初始版本，来源：[触发建立这个 Skill 的事件]

资产二：判断"要不要写 Skill"的三个问题

在每次任务结束后，花 30 秒问自己：

text

问题一：这次任务里，有没有我需要专门在 prompt 里解释的规则？
→ 有：这条规则应该进 Skill，不应该每次都在 prompt 里重复

问题二：AI 犯了一个错，是因为它不知道某个项目特有的约定？
→ 是：这个约定应该进 Skill 的已知坑或禁止行为

问题三：这次任务的处理方式，下次遇到类似情况我会复用吗？
→ 会：把执行步骤写进 Skill，下次不用重新想

三个问题，有一个回答"是"，就花 15 分钟写或更新 Skill。

资产三：Skill 质量检查清单

在把一条规则写进 Skill 之前，逐项确认：

text

□ 这条规则有没有写明"为什么"，而不只是"是什么"？
□ 这条规则是通用规则还是本次特殊情况的变通？
  （如果是变通，写进代码注释，不要写进 Skill）
□ 这条规则有没有配合示例？
  （有示例的规则执行率高于无示例的规则约 60%）
□ 这条规则有没有对应的禁止行为？
  （很多规则需要一个正面描述 + 一个反面约束才完整）
□ 如果这条规则过期了，什么事件会触发我来更新它？
  （没有更新触发器的规则，终将变成误导）

资产四：个人 Skill 库目录结构

text

.claude/
├── skills/
│   ├── [task_type_1].md
│   ├── [task_type_2].md
│   └── ...
├── CLAUDE.md          # 项目级总览，加载所有 Skill 的入口
└── memory/
    └── [YYYY-MM-DD]-[task]-learnings.md  # 单次任务的临时学习记录

CLAUDE.md 的基本结构：

Markdown

# 项目名称 - AI 工作指南

## 快速概览
[一段话描述项目是什么]

## 技术栈
[主要技术栈列表]

## 常用命令
- 测试：[命令]
- 构建：[命令]
- 开发服务器：[命令]

## 激活的 Skill
本项目所有 AI 任务默认加载以下 Skill：
- .claude/skills/naming_conventions.md
- .claude/skills/error_handling.md
- .claude/skills/unit_test_quality.md

特定任务额外加载：
- Bug 修复：.claude/skills/bug_fix.md
- 依赖升级：.claude/skills/dependency_upgrade.md
- PR 相关：.claude/skills/pr_description.md

## 最新更新的坑（滚动更新，保留最近 5 条）
- [日期] [简要描述]

资产五：Skill 版本日志格式

每次更新 Skill，在文件底部追加：

Markdown

## 版本历史

v1.0 (2026-04-03)
来源：[触发建立这个 Skill 的具体事件]
内容：初始版本

v1.1 (2026-04-18)
来源：[触发更新的具体事件，越具体越好]
变更：新增 [规则名]，原因：[为什么加这条]
删除：[如果有删除的话]

v1.2 (2026-05-07)
来源：...

版本日志不只是记录改了什么，更重要的是记录为什么改。

一个没有来源说明的规则，三个月后你自己也不知道为什么有它。一个有来源说明的规则，三年后你打开文件，还能读到当初那个决定背后的故事。

故事，是让知识有生命力的东西。

我是【一只阿木木】——公开建造我的 AI 第二大脑。

普通人如何用 AI 搭建自己的知识操作系统？

一个程序员出身的知识工作者，公开记录自己如何用 AI 工具搭建个人知识系统、把读过的书和做过的项目变成可复用资产的全过程。

欢迎加入行动营👇获取更多Obsidian + AI数字大脑实践

我相信：在 AI 时代，每个普通人都该拥有一个自动生长的知识系统

欢迎关注【一只阿木木】🌊