沉淀个人 Skills

Skills（可复用的 AI 工作流能力包）不是一段更长的提示词，而是一组能被 AI 编程助手按需读取的指令、脚本、模板和参考资料。它的价值不在于“让提示词更复杂”，而在于把已经验证有效的工作方式稳定复用。

这篇文章面向已经在使用 Claude Code、Codex 等 AI 编程助手的读者。你不需要先设计一套庞大的知识库；只要有一个重复出现的工作流，就可以开始沉淀第一个个人 Skill。

本文解决三个问题：

• 为什么 Skills 值得单独沉淀。
• 为什么个人应该维护自己的 Skills 仓库。
• 如何基于 skills-template 搭建、安装和持续使用自己的 Skills。

Skills 解决什么问题

AI 编程助手最常见的浪费，不是模型不会做事，而是你每次都要重新解释同一批背景：

• 这个项目如何写文档。
• 代码审查要看哪些风险。
• 修 Bug 时先收集什么证据。
• 新增页面要遵循哪些结构和校验。
• 常用脚本在哪里，什么时候运行。

如果这些内容只留在聊天记录里，它们很快就会失效：新会话看不到，换工具用不了，换机器也无法迁移。Skills 把这些重复解释变成可维护文件，让 agent 在合适任务中直接读取。

一个 Skill 值得沉淀，通常满足三个条件：

判断问题	说明
是否重复出现	只做一次的上下文不需要沉淀，反复出现的流程才值得写成 Skill。
是否能改善执行质量	如果它能减少漏项、统一标准、降低返工，就值得沉淀。
是否可以被验证	好的 Skill 应该包含检查点、命令或验收标准，而不只是抽象建议。

个人 Skills 仓库为什么重要

个人 Skills 仓库是你的 AI 工作流资产库。它保存的不是某一次对话，而是你长期打磨出来的工作方式。

适合进入个人 Skills 仓库的内容包括：

类型	示例	价值
项目约定	文档 frontmatter、目录结构、命名规则	减少每次解释项目规则的成本
技术栈偏好	Vue 组件组织方式、后端分层方式、测试风格	让 agent 输出更贴近你的默认实践
审查清单	安全、性能、边界条件、回归风险	避免代码审查只看表面 diff
调试流程	先复现、再定位、再最小修复、最后验证	防止直接猜原因和盲改
写作标准	术语解释、结构顺序、验证要求	保持长期文档风格一致
辅助脚本	校验、安装、批处理、生成模板	把人工步骤变成可复现动作

更进一步看，Skills 会成为你使用 AI 时的个人资本。未来人与人之间的差距，不只在于谁能访问更强的模型，也在于谁把自己的经验、判断标准和工作流沉淀成了可复用资产。

当两个开发者使用同一个 AI 工具时，拥有个人 Skills 的人更容易让 agent 理解自己的默认标准：代码如何分层、错误如何处理、测试要覆盖哪些边界、文档应该怎么写。即使某次使用的不是旗舰模型，只要 Skill 写清楚了约束、检查点和示例，模型也更可能输出符合规范的代码，而不是每次都从零猜测你的偏好。

没有个人 Skills	有个人 Skills
每次重新解释代码规范和工作流	让 agent 直接读取沉淀过的规则
输出质量更依赖当次模型能力和提示词状态	输出质量同时受模型能力和个人资产支撑
经验留在聊天记录里，难以迁移	经验进入 Git 仓库，可复用、可迭代、可迁移
换工具、换机器后重新磨合	通过安装同一份 Skills 快速恢复工作方式

它的长期价值来自复利。一次成功的工作流，如果被写入 Skill，下次就不需要从零解释；一次修正后的检查清单，如果被提交到仓库，未来所有相似任务都会受益。

提示

个人 Skills 仓库不等于团队规范仓库。个人仓库优先服务你自己的习惯、偏好和常用工具；当某些 Skills 被多人反复验证后，再考虑迁移成团队共享资产。

注意

个人 Skills 可以开源一部分，但不建议不加筛选地公开全部沉淀。通用模板、目录结构、创建方法和不含业务细节的流程适合开源；真正代表你竞争力的项目经验、审查标准、排障路径和长期打磨出的偏好，应先判断是否适合公开。它们不是普通配置文件，而是你使用 AI 的核心资产。

用 skills-template 搭建仓库

可以从 skills-template 开始创建自己的 Skills 仓库。模板仓库的作用是提供基础目录、安装脚本和校验入口，让你不用从空目录开始组织结构。

推荐结构如下：

skills-template/
├─ skills/
│  └─ example-skill/
│     ├─ SKILL.md
│     ├─ references/
│     ├─ scripts/
│     └─ assets/
├─ scripts/
├─ tests/
├─ README.md
└─ CHANGELOG.md

各目录的职责应保持清晰：

路径	职责
skills/<skill-name>/SKILL.md	Skill 的入口说明，包含触发条件、核心流程和必要约束。
skills/<skill-name>/references/	放长文档、规范说明、详细案例，只在需要时读取。
skills/<skill-name>/scripts/	放与该 Skill 强相关的辅助脚本。
skills/<skill-name>/assets/	放模板、示例文件、静态资源。
scripts/	放仓库级安装、同步、校验脚本。
tests/	放用于验证仓库结构和脚本行为的测试。
CHANGELOG.md	记录 Skills 的新增、调整和不兼容变化。

SKILL.md 应该保持轻量。它负责告诉 agent “什么时候用、按什么顺序做、必要时读哪些材料”，不应该把所有知识都塞进入口文件。

一个 Skill 应该怎么写

最小的 SKILL.md 可以从三部分开始：

---
name: writing-project-docs
description: 为当前项目新增或改写中文文档页时使用
---

# Writing Project Docs

当任务涉及新增、改写或重组项目文档时使用本 Skill。

## 流程

1. 先阅读附近同类页面，匹配 frontmatter、标题层级和语气。
2. 明确读者、目标、边界和验证方式。
3. 写作时保留命令、路径和代码标识符的原始语言。
4. 完成后运行文档构建命令验证。

## 需要时读取

- 页面结构不清楚时，读取 `references/page-structure.md`。
- 涉及发布检查时，读取 `references/release-checklist.md`。

这个例子不追求完整，而是强调边界：入口文件负责调度，细节文件负责补充。

搭建完成后如何使用

仓库搭好后，日常使用通常分为四步。

1. 安装到本机 Skills 目录

常见目标目录是 ~/.agents/skills/。具体命令以 skills-template 仓库中的脚本为准，形式通常类似：

bash scripts/install-codex.sh

如果安装脚本支持 copy 和 link 两种模式，可以按使用方式选择：

模式	适合场景	特点
copy	想安装一个稳定快照	安装后不受源仓库继续修改影响
link	正在频繁编辑和调试 Skill	源仓库修改会立即反映到本机 Skills 目录

2. 在任务中触发 Skill

触发方式有两种：

方式	示例	适合场景
直接点名	$writing-project-docs 帮我新增一篇文档	你明确知道要使用哪个 Skill
任务匹配	帮我写一篇项目文档，并保持现有风格	让 agent 根据 description 判断是否使用

为了更稳定地触发，description 要写清楚适用任务，不要写成泛泛的“提高效率”。

3. 持续更新 Skill

不要一次性设计几十个 Skills。更稳妥的方式是从一个高频工作流开始，在真实任务中迭代：

1. 第一次成功完成任务后，记录关键步骤。
2. 第二次遇到同类任务时，把重复步骤写入 SKILL.md。
3. 如果入口文件变长，把背景资料拆到 references/。
4. 如果某个步骤可以自动化，把它做成 scripts/。
5. 每次提交前运行校验脚本。

4. 迁移到新机器或新工具

个人 Skills 仓库应该进入 Git。换机器时，克隆仓库并重新运行安装脚本即可。换到兼容 Skills 目录结构的工具时，也可以复用同一份 skills/ 内容，只需要调整安装目标目录。

应该沉淀什么，不应该沉淀什么

内容	是否适合沉淀	原因
重复工作流	适合	能减少反复解释和遗漏步骤。
质量标准	适合	能稳定输出质量，例如审查清单和验收标准。
项目约定	适合	能让 agent 更快贴合项目风格。
已验证命令	适合	能把人工操作变成可复现步骤。
一次性上下文	不适合	很快过期，容易污染后续任务。
密钥和凭证	不适合	不应写入源码或公开仓库。
未验证猜测	不适合	会把错误经验固化成规则。
大段无结构笔记	不适合	agent 难以判断何时读取、如何使用。

最小实践路径

从最小闭环开始：

1. 基于 skills-template 创建自己的仓库。
2. 只选择一个重复工作流，创建第一个 Skill。
3. 连续使用一周，记录哪里触发稳定、哪里仍要补充说明。
4. 把过长细节拆到 references/，把可自动化步骤放到 scripts/。
5. 运行校验脚本并提交。
6. 等这个 Skill 真正稳定后，再创建下一个。

沉淀 Skills 的重点不是“写很多规则”，而是让每一条规则都来自真实任务，并能在下一次任务中减少解释成本、降低错误概率。