AI Agent 的"肌肉记忆"：从零手撸 Skill 到自动生成从 YAML 到 Markdown 正文，逐行拆解 S

1. AI Agent 的"肌肉记忆"：从零手撸 Skill 到自动生成

什么是 Skill

Skill（技能）是 AI Agent 的程序性知识载体，本质上是一个结构化的 Markdown 文件。不同 Agent 框架对 Skill 的存放路径各有约定：

Codex（OpenAI）：Skill 存放在项目根目录的 .codex/skills/{name}/SKILL.md，与代码仓库一起版本控制，团队成员共享同一份 Skill。
QoderWork：Skill 存放在用户目录 ~/.qoderwork/skills/{name}/SKILL.md，属于个人配置，跨项目通用。
Claude Code：通过 CLAUDE.md 或项目级指令文件承载类似功能，存放位置灵活。

无论路径如何，核心思想一致：将"如何做某件事"的最佳实践固化为可复用的操作手册。

AI 虽然拥有广博的知识，但缺乏项目特定的上下文、团队约定的流程、以及反复踩坑后沉淀的经验。Skill 填补了这个空白——当你发现某个复杂任务需要多次工具调用才能完成，或者某个错误反复出现时，就应该考虑将其封装为 Skill。

触发创建 Skill 的典型场景包括：复杂任务成功执行（涉及 5 次以上工具调用）、克服了特定错误、用户纠正了 Agent 的做法、发现了非显而易见的工作流，或用户明确要求记住某个流程。

SKILL.md 的结构解剖

一个典型的 Skill 文件由两部分组成：YAML 前置元数据和 Markdown 正文。

YAML 前置元数据

---
name: skill-name
description: 一句话描述这个技能做什么、何时使用
version: 1.0.0
---

三个字段中，name 和 description 是必填项。name 必须是小写字母、数字和连字符的组合，不能以连字符开头或结尾，最长 64 个字符，同时作为技能目录的名称。description 至关重要——它是技能被检索时的核心索引，需要用第三人称写清楚"做什么"和"何时用"，例如"生成 PDF 报告。当用户要求输出 PDF 或打印就绪文档时使用"。version 是可选的语义化版本号。

Markdown 正文

正文没有强制格式，但推荐包含以下模块：

步骤：按顺序列出具体操作，每条指令要精确到可直接执行
陷阱：记录容易踩坑的地方及原因
验证：说明如何确认操作成功

这种结构的目的是让 Agent 在执行任务时有明确的检查清单，而不是依赖模糊的记忆。

从零构建一个代码审查 Skill

让我们通过一个完整的例子来演示如何创建一个代码审查 Skill。假设你在多次代码审查后发现了一些重复的模式和容易忽略的点，决定将这些经验固化下来。

第一步：明确职责边界

好的 Skill 应该聚焦单一职责。代码审查 Skill 的职责是：在代码合并前，按照团队约定的标准检查代码质量，并给出可执行的改进建议。它不负责编写代码、不负责运行测试、不负责部署——这些是其他 Skill 或工作流的职责。

第二步：编写 SKILL.md

在项目的 Skill 目录下创建 code-review/SKILL.md，内容如下：

---
name: code-review
description: 在代码合并前进行系统性审查。当用户要求 review PR、检查代码质量、或提交前验证时使用。覆盖安全性、性能、可读性和规范一致性四个维度。
version: 1.0.0
---

# 代码审查清单

## 审查维度

### 1. 安全性
- 检查是否有硬编码的密钥、密码或 API Token
- 验证用户输入是否经过过滤和转义
- 确认敏感操作有权限校验
- 检查 SQL/命令注入风险

### 2. 性能
- 识别 N+1 查询问题
- 检查循环内的数据库调用或网络请求
- 确认大对象没有被不必要地序列化
- 检查是否有内存泄漏风险（未关闭的连接、监听器等）

### 3. 可读性
- 函数是否超过 50 行？如果是，考虑拆分
- 变量命名是否自解释？避免 `data`、`temp`、`result` 等模糊命名
- 复杂逻辑是否有注释说明"为什么"而非"是什么"
- 公共 API 是否有文档字符串

### 4. 规范一致性
- 遵循项目的编码约定（如 AGENTS.md 或 CONTRIBUTING.md 中定义）
- 提交信息符合 Conventional Commits 规范
- 新增代码有对应的单元测试
- 类型注解完整（如果使用 TypeScript/Python）

## 输出格式

审查结果按以下结构组织：

1. **严重问题**（阻断合并）：安全问题、数据丢失风险
2. **建议改进**（不阻断但强烈推荐）：性能问题、可读性问题
3. **风格建议**（可选）：命名、格式化等

每个问题附带：
- 文件路径 + 行号
- 问题描述
- 修复建议（给出具体代码片段）

## 陷阱

- 不要只说"这里有问题"，必须说明"为什么有问题"和"怎么改"
- 避免主观偏好（如"我不喜欢这个命名"），除非违反项目规范
- 对于第三方库的使用，先查官方文档再提建议，不要凭记忆
- 如果不确定某个判断，标注"待确认"而非断言

## 验证

审查完成后，确认：
- [ ] 所有严重问题都已标记并给出修复方案
- [ ] 没有遗漏明显的空指针/未处理异常
- [ ] 建议的代码片段可以直接复制使用
- [ ] 审查意见的语气是建设性的，非指责性的

第三步：逐行解读示例

下面对上面这个 SKILL.md 逐行拆解，说明每一行为什么这么写、建议怎么写、以及要避免什么写法。

第 1-2 行：YAML 分隔符

---
name: code-review

--- 是 YAML frontmatter 的起始分隔符，告诉解析器"从这里开始是元数据"。紧接着的 name 字段是 Skill 的唯一标识符，同时也是它在文件系统中的目录名。

为什么用 code-review 而不是 CodeReview 或 code_review？kebab-case（小写加连字符）是跨平台兼容性最好的命名方式——Windows 文件名不区分大小写，CodeReview 和 codereview 可能冲突；下划线在某些 URL 场景下会被转义。连字符则没有这些问题。

建议：code-review、generate-pdf、debug-performance。用动名词或名词短语，一眼看出这个 Skill 做什么。
避免：my-skill、test1、do-stuff（无意义）；Code-Review（大写开头）；code_review（下划线）。

第 3 行：description

description: 在代码合并前进行系统性审查。当用户要求 review PR、检查代码质量、或提交前验证时使用。覆盖安全性、性能、可读性和规范一致性四个维度。

这是整个 Skill 中最重要的字段。Agent 在每个对话轮次开始时，只会看到所有 Skill 的 name + description，然后据此决定是否加载这个 Skill。description 写得好不好，直接决定这个 Skill 能不能被用上。

这行 description 做了三件事，用句号分隔：

第一句"在代码合并前进行系统性审查"说明做什么——定义了 Skill 的核心功能。

第二句"当用户要求 review PR、检查代码质量、或提交前验证时使用"说明何时用——列举了三种常见的触发场景，覆盖了用户可能用的不同说法（"review PR"是英文说法，"检查代码质量"是中文说法，"提交前验证"是流程说法）。

第三句"覆盖安全性、性能、可读性和规范一致性四个维度"说明覆盖范围——让 Agent 知道这个 Skill 的边界在哪里，不会误用到其他场景。

建议：用第三人称，包含多个触发关键词。想象用户会用多少种不同的方式提出同一个需求，把常见的说法都写进去。用句号分隔"做什么"、"何时用"、"覆盖范围"三个信息块。
避免：只写"帮助做代码审查"——太短、太模糊，Agent 无法判断什么时候该加载它。也避免写成第一人称"我来帮你审查代码"——description 是给 Agent 的检索索引，不是给用户的问候语。也避免用分号或逗号把三件事挤成一句长句，句号分隔更利于 Agent 解析。

第 4 行：version

version: 1.0.0

语义化版本号。虽然可选，但建议写上。当你的 Skill 被多人共享（比如放在 Codex 的项目目录里随仓库版本控制），版本号能帮团队成员判断自己用的是不是最新版。

建议：遵循 semver 规范（MAJOR.MINOR.PATCH）。功能不变只改措辞改 PATCH，新增检查项改 MINOR，大幅重构改 MAJOR。
避免：不写版本号（多人协作时无法追踪变更）；写 v1.0（不一致的格式）。

第 5 行：YAML 结束分隔符

---

frontmatter 的结束标记。之后的一切内容都是 Markdown 正文，不再被当作元数据解析。

注意：这个 --- 前后必须各有一个空行，否则某些解析器会把正文的第一行也吞进元数据里。

第 6 行：一级标题

# 代码审查清单

一级标题是 Skill 正文的入口。它不需要和 name 一致，但应该用人类可读的方式概括 Skill 的内容。

建议：简洁明了，让人一眼知道这份手册的主题。代码审查清单、PDF 生成流程、性能诊断步骤 都是好标题。
避免：和 name 完全重复（如 # code-review）——读者看到英文目录名又看到英文标题，信息冗余。也避免写成花哨的标语（如 # 让你的代码更优雅）——标题是功能性的，不是营销文案。

第 7 行：二级标题

## 审查维度

二级标题将正文划分为逻辑区块。"审查维度"这个标题暗示接下来的内容是按不同维度组织的检查清单。

建议：二级标题应该概括其下所有子内容的共同主题。审查维度、输出格式、陷阱、验证 都是功能性标题，Agent 读到就知道这一节讲什么。
避免：相关内容、其他、补充说明 这种模糊标题——Agent 无法从标题判断这一节的重要性。

第 8-9 行：三级标题 + 第一条检查项

### 1. 安全性
- 检查是否有硬编码的密钥、密码或 API Token

三级标题 1. 安全性 用数字编号，暗示这些维度有明确的顺序（虽然实际执行时顺序不一定严格）。编号还有一个好处：Agent 可以引用"按维度 1 检查"来定位具体位置。

第一条检查项检查是否有硬编码的密钥、密码或 API Token是典型的"动词 + 对象"结构：

动词"检查"告诉 Agent 要做什么动作
对象"硬编码的密钥、密码或 API Token"告诉 Agent 要检查什么

三个对象用顿号并列，因为它们属于同一类问题（都是敏感信息泄露），Agent 可以一次性扫描。

建议：每条检查项都是"动词 + 明确对象"的结构。动词用检查、验证、确认、识别等具体动作词。对象用技术术语（密钥、API Token、SQL 注入），不用抽象概念（安全问题）。
避免：确保代码安全——"确保"是结果导向的词，没有告诉 Agent 具体做什么动作。注意有没有敏感信息——"注意"太模糊，"敏感信息"范围太大。代码安全吗？——疑问句没有给出行动指令，Agent 不知道回答"是"或"否"之后该做什么。

第 10 行

- 验证用户输入是否经过过滤和转义

这条和上一条的区别在于动词从"检查"换成了"验证"。"检查"偏向静态扫描（看代码里有没有），"验证"偏向逻辑判断（看流程里有没有）。用词的微妙差异帮助 Agent 理解不同的检查方式。

建议：根据检查的性质选择动词。"检查"用于静态扫描，"验证"用于逻辑判断，"确认"用于存在性确认，"识别"用于模式发现。
避免：所有条目都用同一个动词（如全部用"检查"）——虽然不会出错，但失去了用词传递的语义信息。

第 13-16 行：性能维度

### 2. 性能
- 识别 N+1 查询问题
- 检查循环内的数据库调用或网络请求
- 确认大对象没有被不必要地序列化
- 检查是否有内存泄漏风险（未关闭的连接、监听器等）

这一组展示了如何写一个完整的检查维度。四条检查项覆盖了性能问题的四个常见来源：查询模式（N+1）、循环中的 IO（数据库/网络）、数据体积（序列化）、资源管理（内存泄漏）。

注意最后一条的括号（未关闭的连接、监听器等）——它用具体例子帮助 Agent 理解"内存泄漏风险"在这个项目语境下指什么。括号里的内容是补充说明，不是新的检查项。

建议：每个维度 3-5 条检查项，覆盖该维度的主要问题类型。用括号补充具体例子来消除歧义。
避免：一个维度下放 15 条检查项（太多，Agent 会遗漏）；或者只放 1 条（太少，覆盖不全）。也避免在括号里写新的检查动作——括号只用于举例说明，不用于新增指令。

第 19-22 行：可读性维度（条件 + 行动模式）

### 3. 可读性
- 函数是否超过 50 行？如果是，考虑拆分
- 变量命名是否自解释？避免 `data`、`temp`、`result` 等模糊命名
- 复杂逻辑是否有注释说明"为什么"而非"是什么"
- 公共 API 是否有文档字符串

这一组用了和前两个维度不同的写法——"条件判断 + 行动建议"模式。

第一条函数是否超过 50 行？如果是，考虑拆分：先给出判断条件（50 行），再给出行动（拆分）。50 是一个明确的阈值，Agent 不需要猜测"多长算长"。

第二条变量命名是否自解释？避免 data、temp、result 等模糊命名：先给出判断标准（自解释），再用反引号列出反面示例（data、temp、result）。反引号在 Markdown 中渲染为等宽字体，视觉上突出这些是"不要用的名字"。

第三条复杂逻辑是否有注释说明"为什么"而非"是什么"：这条特别精妙——它不只是说"要有注释"，而是区分了好的注释（说明为什么）和差的注释（说明是什么）。这直接纠正了 Agent 常见的错误倾向（给代码逐行加"这是什么"的注释）。

建议：当规则有阈值时，明确写出数字（50 行、3 层嵌套、100ms）。当规则容易误判时，给出反面示例（避免 data、temp）。当规则有质量区分时，说明好的做法和差的做法的区别（"为什么"vs"是什么"）。
避免：函数不要太长——多长算长？变量命名要有意义——什么算有意义？要有注释——什么样的注释？这些写法都太模糊，Agent 无法执行。

第 25-28 行：规范一致性维度

### 4. 规范一致性
- 遵循项目的编码约定（如 AGENTS.md 或 CONTRIBUTING.md 中定义）
- 提交信息符合 Conventional Commits 规范
- 新增代码有对应的单元测试
- 类型注解完整（如果使用 TypeScript/Python）

这一组的特点是大量引用外部规范。第一条直接指向AGENTS.md 或 CONTRIBUTING.md，而不是把编码约定抄录在这里。第四条用条件句如果使用 TypeScript/Python，说明这条规则只在特定技术栈下适用。

建议：如果规则已经在项目规范文件中定义，用引用而非抄录。如果规则只在特定条件下适用，用"如果...则..."的条件句明确适用范围。
避免：把 AGENTS.md 里的编码约定完整抄一遍到 Skill 里——两份文件改一处忘一处，最终不一致。也避免把条件性规则写成绝对规则（如"必须有类型注解"——如果项目是 JavaScript 就不适用）。

第 30-38 行：输出格式区

## 输出格式

审查结果按以下结构组织：

1. **严重问题**（阻断合并）：安全问题、数据丢失风险
2. **建议改进**（不阻断但强烈推荐）：性能问题、可读性问题
3. **风格建议**（可选）：命名、格式化等

每个问题附带：
- 文件路径 + 行号
- 问题描述
- 修复建议（给出具体代码片段）

这一节定义了 Skill 产出的结构。它做了两件事：

第一，用有序列表定义问题的严重等级。每个等级用加粗标题 + 括号说明 + 冒号列举的格式：**严重问题**（阻断合并）：安全问题、数据丢失风险。加粗让等级名称醒目，括号说明决策影响（阻断合并 vs 不阻断），冒号后面列举典型场景帮助 Agent 归类。

第二，用无序列表定义每个问题必须包含的字段。文件路径 + 行号用加号连接，表示这两个信息要一起提供（不能只有路径没有行号）。修复建议（给出具体代码片段）用括号强调"具体代码片段"——不是泛泛地说"建议重构"，而是要给出能直接复制的代码。

建议：如果 Skill 的产出需要被下游消费（比如审查结果要贴到 PR 评论里），输出格式区尤为重要。用加粗标记关键分类，用括号补充决策影响，用有序列表表示优先级。
避免：不写输出格式，指望 Agent "自然地"给出好的结果。也避免用自由散文描述输出格式（如"请把结果整理一下告诉我"）——散文没有结构约束，Agent 每次输出的格式都不一样。

第 40-44 行：陷阱区

## 陷阱

- 不要只说"这里有问题"，必须说明"为什么有问题"和"怎么改"
- 避免主观偏好（如"我不喜欢这个命名"），除非违反项目规范
- 对于第三方库的使用，先查官方文档再提建议，不要凭记忆
- 如果不确定某个判断，标注"待确认"而非断言

陷阱区和步骤区的根本区别：步骤区告诉 Agent 做什么，陷阱区告诉 Agent 不要做什么。每一条陷阱都来自实际踩坑的经验。

第一条不要只说"这里有问题"，必须说明"为什么有问题"和"怎么改"：这是典型的"禁令 + 替代方案"结构。前半句说不要做什么，后半句说应该做什么。如果只写前半句，Agent 知道不能说"这里有问题"，但不知道应该说什么。

第二条避免主观偏好（如"我不喜欢这个命名"），除非违反项目规范：括号里的例子让 Agent 理解什么是"主观偏好"——不是所有命名建议都是主观的，只有"我不喜欢"这种没有客观依据的才是。除非违反项目规范是例外条件，说明如果命名确实违反了 AGENTS.md 里的约定，那就可以提。

第三条对于第三方库的使用，先查官方文档再提建议，不要凭记忆：这条针对的是 Agent 的一个常见问题——对不熟悉的库凭训练记忆给出过时的 API 建议。"先查官方文档"给出了正确的做法。

第四条如果不确定某个判断，标注"待确认"而非断言：这条教 Agent 处理不确定性。与其给出一个可能错误的断言，不如标注"待确认"让人类判断。

建议：每条陷阱都用"不要 X，应该 Y"的结构。用括号给出具体例子帮助 Agent 理解抽象概念。用"如果...则..."处理例外情况。
避免：只写禁令不给替代方案（不要乱提建议——什么叫"乱"？应该怎么做？）。把项目通用规范写在这里（那是 AGENTS.md 的职责）。写过于抽象的陷阱（注意质量——注意什么？怎么注意？）。

第 46-51 行：验证区

## 验证

审查完成后，确认：
- [ ] 所有严重问题都已标记并给出修复方案
- [ ] 没有遗漏明显的空指针/未处理异常
- [ ] 建议的代码片段可以直接复制使用
- [ ] 审查意见的语气是建设性的，非指责性的

验证区是 Skill 执行完毕后的自检清单。它的作用是让 Agent 在输出结果之前做最后一轮检查。

- [ ] 是 Markdown 的 checkbox 语法，渲染为一个可勾选的方框。这个语法有两个作用：视觉上清晰（一眼看出有几项要检查），语义上暗示"逐项勾选"的动作（不是扫一眼就过，而是一项一项确认）。

四条验证项的设计原则：

第一条所有严重问题都已标记并给出修复方案：对应输出格式区的"严重问题"等级和"修复建议"字段，验证输出是否完整。

第二条没有遗漏明显的空指针/未处理异常：这是一个"负面验证"——不是验证做了什么，而是验证没漏什么。这类验证项通常针对历史上最常遗漏的问题。

第三条建议的代码片段可以直接复制使用：验证修复建议的质量。不是"有代码片段"就行，而是"可以直接复制使用"——意味着语法正确、上下文完整。

第四条审查意见的语气是建设性的，非指责性的：验证输出的语气。这条看似主观，但"建设性 vs 指责性"有明确的区分标准（前者说"这个函数可以拆分为..."，后者说"这个函数写得太烂了"）。

建议：验证项应该是可客观判断的。数量控制在 3-5 条，太多会变成形式主义。混合"正面验证"（做了什么）和"负面验证"（没漏什么）。
避免：写确保审查质量高——"质量高"无法客观判断。写 15 条验证项——Agent 会机械勾选，失去自检的意义。把验证区和步骤区混在一起——步骤是"做"，验证是"查"，分开写逻辑更清晰。

第四步：测试与迭代

创建 Skill 后，在实际审查中验证它的效果。如果发现某个检查项总是被遗漏，补充到清单中；如果某个建议过于模糊，细化为具体规则。每次使用后都应该问自己：这次审查有没有用到 Skill 里没写的东西？如果有，就把它加进去。

其实你不需要手撸：用 create-skill 自动生成

上面花了大量篇幅讲解 SKILL.md 的结构和写法，目的是让你理解 Skill 的内在逻辑。但在实际使用中，你完全不需要从零手写——借助 create-skill 这个 Skill，Agent 可以自动帮你生成符合规范的 SKILL.md。

create-skill 的工作方式

create-skill 的核心思路是"对话式生成"：你不需要自己写 YAML 元数据、不需要纠结步骤怎么措辞、不需要手动设计验证清单。你只需要用自然语言告诉 Agent 你想让 Skill 做什么，它会通过多轮对话收集必要信息，然后自动生成完整的 SKILL.md 文件。

典型的使用流程如下：

flowchart TD
    A[告诉 Agent 你想创建什么 Skill] --> B[Agent 通过对话收集需求]
    B --> C[Agent 生成 SKILL.md 初稿]
    C --> D[你审查并反馈修改意见]
    D --> E[Agent 迭代优化]
    E --> F{满意?}
    F -->|否| D
    F -->|是| G[Skill 创建完成]
    
    style A fill:#e0f7fa,stroke:#00838f,stroke-width:2px,rx:8
    style B fill:#e0f7fa,stroke:#00838f,stroke-width:2px,rx:8
    style C fill:#e0f7fa,stroke:#00838f,stroke-width:2px,rx:8
    style D fill:#e0f7fa,stroke:#00838f,stroke-width:2px,rx:8
    style E fill:#e0f7fa,stroke:#00838f,stroke-width:2px,rx:8
    style F fill:#fff9c4,stroke:#f9a825,stroke-width:2px,rx:8
    style G fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,rx:8

为什么还要学手撸

既然有自动化工具，为什么还要花时间理解 Skill 的结构？两个原因：

第一，审查和修改的能力。create-skill 生成的初稿不一定完美，你需要能判断哪里写得好、哪里需要调整。如果你完全不了解 SKILL.md 的结构，面对生成的内容就只能全盘接受或全盘否定，无法做精细的修改。

第二，表达需求的能力。你告诉 Agent"帮我创建一个 Skill"时，描述的质量直接决定生成结果的质量。理解了 Skill 的结构后，你能给出更精确的指令，比如"我需要一个代码审查 Skill，重点覆盖安全性和性能两个维度，输出格式要分三级严重程度"——这种指令比"帮我做个代码审查的东西"产出的结果好得多。

简单来说：create-skill 帮你省去的是"写"的工作量，但"想清楚要什么"和"判断写得好不好"这两件事，仍然需要你自己来做。理解 Skill 的结构，就是为了做好这两件事。

Skill 的生命周期

Skill 不是一次性产物，它会随着使用不断进化。整个生命周期可以分为四个阶段：

flowchart TD
    A[识别需求] --> B[创建初版]
    B --> C[实际使用]
    C --> D{发现问题?}
    D -->|是| E[更新 SKILL.md]
    D -->|否| F[保持稳定]
    E --> C
    F --> G{长期未使用?}
    G -->|是| H[归档或删除]
    G -->|否| I[持续维护]
    I --> C
    
    style A fill:#e0f7fa,stroke:#00838f,stroke-width:2px,rx:8
    style B fill:#e0f7fa,stroke:#00838f,stroke-width:2px,rx:8
    style C fill:#e0f7fa,stroke:#00838f,stroke-width:2px,rx:8
    style D fill:#fff9c4,stroke:#f9a825,stroke-width:2px,rx:8
    style E fill:#e0f7fa,stroke:#00838f,stroke-width:2px,rx:8
    style F fill:#e0f7fa,stroke:#00838f,stroke-width:2px,rx:8
    style G fill:#fff9c4,stroke:#f9a825,stroke-width:2px,rx:8
    style H fill:#ffebee,stroke:#c62828,stroke-width:2px,rx:8
    style I fill:#e0f7fa,stroke:#00838f,stroke-width:2px,rx:8

创建阶段的关键是快速产出可用版本，不要追求完美。使用阶段的反馈才是 Skill 价值的真正来源。当一个 Skill 连续数月未被触发，说明它可能已经过时或与当前工作流脱节，这时应该果断归档或删除，避免干扰检索。

最佳实践

保持单一职责

一个 Skill 只做一件事。如果你发现自己在一个 Skill 里写了"代码审查"和"部署检查"两个完全不相关的流程，拆成两个 Skill。单一职责的 Skill 更容易被准确检索，也更容易维护。

描述要具体可搜索

description 字段是 Skill 被找到的关键。避免写"帮助做代码相关的事情"这种模糊描述，改为"在代码合并前进行系统性审查。当用户要求 review PR、检查代码质量、或提交前验证时使用"。后者包含了多个触发关键词，能被不同方式的提问命中。

步骤要可执行

"检查代码质量"不是一个好步骤，"检查是否有硬编码的密钥、密码或 API Token"才是。可执行的步骤意味着 Agent 不需要再猜测"怎么做"，直接按清单逐项核对即可。

及时更新

每次使用 Skill 后发现遗漏或错误，立即更新。不要等到"有空再整理"——那个时刻永远不会到来。Skill 的价值在于它反映的是最新的、经过验证的最佳实践，过时的 Skill 比没有 Skill 更危险。

避免冗余

如果某个约定已经在项目的规范文件（如 AGENTS.md、CONTRIBUTING.md）中定义，Skill 里只需引用，不要重复抄录。规范文件是项目级的权威参考，Skill 是任务级的操作手册，两者分工不同。重复的内容会导致维护困难——改了一处忘了另一处，最终产生不一致。

总结

手撸一个 Skill 的核心思路很简单：把"做过一次且做得不错的事"变成"下次可以直接照着做的清单"。YAML 元数据让它能被找到，Markdown 正文让它能被执行，持续的迭代让它保持鲜活。

Skill 不是文档，不是笔记，不是备忘录——它是可操作的程序性知识。当你下一次发现自己或你的 Agent 又在重复同样的思考过程时，那就是创建 Skill 的最佳时机。