产物一·技能（上）：SKILL.md 的解剖

3.1 frontmatter：给模型看的说明书

SKILL.md 分两部分：两道 --- 之间的 YAML frontmatter，和下面的 Markdown 正文。它们面向的读者不同——frontmatter 是给模型做决策看的，正文是给模型执行时读的。

frontmatter 常用字段就这么几个：

---
name: release-notes
description: 把改动整理成面向使用者的发布说明。当用户要写发布说明、release notes 或 changelog 时使用。
allowed-tools: Read, Bash(git log *), Bash(git diff *)
---

description 是全篇最该用心写的一行，第 4 章整章都在讲它。allowed-tools 有个容易误解的点：它不是限制技能只能用这些工具，而是把这些工具在当轮预先批准、免去逐次授权；其他工具依然可用，仍走你的常规权限设置。而且这个授权在你发出下一条消息后就失效。

3.2 正文：给模型下的指令

frontmatter 下面的正文，就是技能被调用后进入对话的那段指令。写正文有一条心法：它会作为一条消息留在上下文里，之后不会被重新读取。所以正文该写成”贯穿整个任务的规矩”，而不是”一次性的步骤清单”。

我们的 release-notes 正文，就是那套三分类规则。你可以把它写得比第 2 章更完整，因为现在它有独立文件，篇幅不再挤占别处：

把提供给你的改动整理成一份发布说明。$ARGUMENTS

## 分类规则
- 新增：使用者能用到的新能力
- 修复：修好的、会影响使用者的问题
- 破坏性变更：需要使用者改配置或改用法的变化

## 写作规则
- 每条一句话，主语是使用者能感知的东西，不是内部函数名
- 纯内部重构、依赖升级、格式调整一律不写
- 破坏性变更单独成段，每条附一句"你需要做什么"

3.3 两类内容：参考知识 vs 任务流程

技能装的东西大体分两类，分清它们能帮你决定要不要让模型自动调用。

参考知识型：一套领域规矩或风格，比如”我们的错误响应长什么样""发布说明怎么分类”。这类适合让模型自动加载——你写代码写到相关处，它自己把规矩挂上来。release-notes 偏这一类。

任务流程型：一串有副作用的动作，比如提交、部署、发消息。这类你通常不希望模型自作主张——你可不想让它觉得”代码看起来好了”就自己去部署。给这类技能加上 disable-model-invocation: true，把触发权攥在自己手里。

3.4 放个人目录还是项目目录

同一个技能放在哪，决定了谁能用它：

判据很直接：这套规矩是你个人的习惯，还是团队的共识？ release-notes 如果是全队都要遵守的发布格式，就该放进项目的 .claude/skills/ 并提交到版本库，这样同事 clone 下来就自带这条规矩。我们从第 2 章的个人目录起步，是为了先跑通；等第 9 章打包时，它会正式落到团队能共享的地方。

同名冲突的规则也顺带记一下：跨层级时，企业级盖过个人级，个人级盖过项目级；同名的技能会盖过同名的命令文件。