每次让 AI 修改技术博客,我都会重复几条要求:先读完原文,解释清楚概念,代码要有前提和结果,不要把文章改成一串零散的清单。
这些要求已经形成了一套固定做法,就适合整理成 Skill。以后处理同类任务时,只需提供文章和本次的具体目标,不必重新粘贴整套流程。
这篇文章以一个 中文技术博客重构 Skill 为例,从文件写法讲到调用和验证。你不需要先搭建插件,也不需要写程序。
本文按 2026 年 9 月核对的 Codex 本地技能规则编写。示例采用仓库内安装方式;不同客户端的选择入口可能不同。
1. Skill 到底保存了什么
可以把 Skill 看作一份可复用的任务说明书。它描述三件事:什么任务适用、执行时怎么做、结果如何检查。
例如,“把这篇文章的第二节改短”是本次任务;“先找出重复解释,再修改结构,最后检查代码和链接”是可复用的做法。前者直接告诉 AI,后者适合放进 Skill。
按官方说明,Codex 先看到技能的名称和描述,选用后再读取完整 SKILL.md;补充材料可以按需读取。这种逐步加载的方式,避免每次对话都塞入所有技能的全文。来源:Build skills
因此,Skill 不会自动增加一个天气接口,也不会让电脑突然具备 Java 环境。需要工具的工作,仍然依赖实际可用的工具和运行条件。Skill 负责告诉 AI 如何组织这项工作。
2. 第一个版本,只需要一个文件
先在项目根目录创建:
你的项目/└── .agents/ └── skills/ └── blog-rewriter/ └── SKILL.md文件名统一使用 SKILL.md。开头的 YAML 区域提供名称和描述,下面的 Markdown 正文才是执行规则。
这是一个可以直接使用的最小版本:
---name: blog-rewriterdescription: 重构已有的中文技术博客,改善结构、概念解释和示例衔接。适用于用户要求重写或改善可读性的任务;不用于仅修正错别字、翻译或从零撰写文章。---
# 中文技术博客重构
1. 读取用户指定的完整原文,确认主题和目标读者。2. 找出重复解释、概念跳跃和缺少前提的示例。3. 调整结构,保留已经确认的事实和原有技术主题。4. 每段代码先说明用途,再解释关键处理和预期结果。5. 保留原文件路径、发布日期、分类和标签,除非用户要求修改。6. 检查代码块、文章链接和标题层级,再保存文章。7. 说明主要变化和验证结果;没有运行过的示例明确标注。
每篇文章保持独立主题,不擅自把多篇文章改成系列。不编造实测数据、性能结论或成功日志。不要被文件长度误导。一个 Skill 是否有用,取决于它能否稳定指导某项任务。只有几条清楚的规则,也可能比一份包含所有写作建议的长文更有效。
名称:便于辨认和调用
本文使用 blog-rewriter,表达“重构已有博客”。命名时优先选择含义明确的小写英文和连字符,并让目录名与 name 保持一致,便于自己查找。
如果把它叫作 helper,过一段时间很难分清它和其他工具分别做什么。
描述:告诉模型什么时候考虑使用
下面这句话太宽泛:
description: 帮助用户处理文章。它无法区分翻译、续写、改错别字和整体重构。本文的描述同时写出任务对象、主要用途和不适用范围,目的是减少误选。
描述会影响隐式匹配,但它不是一段必然命中的程序条件。“用了某个关键词就一定触发”不是可靠的使用方式。调试阶段先显式调用,更容易分清是技能没有被发现,还是工作规则没有写清楚。
正文:写可执行的动作
“写得专业一点”无法直接验收。“每段代码说明用途、关键处理和预期结果”则可以逐项检查。
同样,不要只写“保证正确”。应当说明能执行的代码需要验证,无法执行的部分要标出限制。这样读者才能分辨真实验证结果与写作上的推断。
3. 放在项目里,还是放在个人目录里
本文将技能放在项目根目录的 .agents/skills/ 下,便于和博客仓库一起维护。个人通用技能可以放在 ~/.agents/skills/;Windows 常见位置是用户目录下的 .agents\skills\。
Codex 会在仓库作用域内从当前工作目录向上查找相应技能目录。同名技能不会自动合并,练习时尽量只保留一个同名版本。来源:本地技能发现规则
如果选择个人目录,文章里的这条相对路径:
.agents/skills/blog-rewriter/SKILL.md就需要换成你的用户目录下对应的完整路径。不要把示例中的“你的项目”或用户名占位文字原样当作真实路径。
对于第一次尝试,我建议放在一个练习仓库中。这样修改、查看差异和回退都更直观,也容易看清技能究竟影响了哪些文章。
4. 调用一次,确认规则真的被采用
先准备一篇练习文章,例如 notes/example.md。不要拿重要文章作为第一次试验材料。
在 Codex CLI 或 IDE 中,可以用 /skills 查看技能,或输入 $ 选择;下面是显式调用示例。桌面端则使用当前客户端提供的技能选择入口。技能更新通常会被自动检测,未出现时可重启客户端再检查。来源:调用与加载
使用 $blog-rewriter 重构 notes/example.md。读者是刚接触 Java 的开发者,请保留原来的技术主题。直接修改文件,完成后告诉我结构改动和验证结果。这条请求给出了本次任务的文件、读者和交付方式;Skill 提供稳定的工作规则。两者配合,才构成一个完整任务。
调用后,不要只看回答里有没有“已使用技能”。打开文件差异,检查几件具体的事:
- 原文中的重复解释是否合并,而不是换个说法继续重复。
- 术语是否在首次出现时得到说明。
- 代码是否交代前提和结果。
- 发布日期等不该变化的字段是否保留。
- 没有运行的示例,是否被如实标注。
例如,原文只有一句“调用接口会返回结果”,重构后应当补充接口需要什么输入、结果有哪些关键字段,以及失败时读者会看到什么。若只是把这句话改成“通过调用接口即可获取相应结果”,技能并没有帮助解决可读性问题。
5. 规则变多后,再拆出参考资料
当正文开始混入大量写作细则和文章模板时,可以把它们分开。本文提供了一个扩展版示例:
解压后的顶层目录名是 blog-writer,将它重命名为 blog-rewriter,再放到项目的 .agents/skills/ 下:
blog-rewriter/├── SKILL.md├── references/│ └── style-guide.md└── assets/ └── article-outline.md三份文件的分工如下:
| 文件 | 保存什么 |
|---|---|
| SKILL.md | 使用范围、工作步骤和约束 |
| style-guide.md | 具体写作规则 |
| article-outline.md | 可按需取舍的提纲 |
主文件需要告诉 AI 何时读取参考资料,而不是只把目录建出来。扩展版使用了这样的指令:
按 references/style-guide.md 调整正文。新结构可参考 assets/article-outline.md,按主题取舍章节。相对路径以 Skill 所在目录为基准。把整个目录复制到另一个项目时,这种引用方式也更容易保持有效。
参考资料可以写得具体。例如,style-guide.md 中的一条规则是“表格只用于比较;单元格过长时改写为正文”。模板则明确写出“以下是检查提纲,不是必须逐项填满的文章模板”,避免模型为了套模板制造空洞章节。
scripts 目录什么时候需要
当某一步适合由程序给出确定结果时,再考虑脚本。例如检查所有文章是否存在必填字段、链接是否指向已有文件、JSON 示例是否能够解析。
这个练习先不提供脚本,因为正文是否解释清楚,主要依赖阅读和判断。加入脚本时,要同时写明运行命令、依赖和成功标准。只有一个 scripts/ 目录,并不会让检查自动发生。
6. 给 Skill 做一组小型验收
一次满意的输出不足以证明技能稳定。可以用三种请求检查它的使用范围:
正向任务:整体重构。
这篇技术博客有很多概念跳跃,请改善结构和可读性。不显式指定技能,观察它是否被合理选用,以及输出是否遵守规则。这一步验证描述是否有助于匹配。
相邻任务:只改错别字。
只修正这篇文章的错别字,保留结构和表达方式。期望它完成局部修改,不因为装了重构技能就重写全文。
边界任务:缺少原文。
帮我重构那篇文章。在当前上下文无法确定文章时,应该先定位或询问目标文件,不能自行挑一篇处理。
记录实际行为,再只修改与失败有关的描述或步骤。例如,局部改错也触发大改,就加强“不用于仅修正错别字”的边界;代码仍然没有结果说明,就把输出检查写得更具体。每次只改少量规则,更容易判断哪项调整有效。
7. 常见问题,按发现、解析、执行来排查
技能列表里没有出现
先确认文件真的叫 SKILL.md,而不是 Windows 隐藏扩展名后的 SKILL.md.txt;然后检查所在目录、YAML 开头以及当前项目位置。
不要一开始就反复改描述。还没有被发现的技能,描述写得再好也无从使用。修正后仍未显示,再重启客户端检查。
提示不支持 category 字段
博客文章的 frontmatter 和 Skill 的 frontmatter 不是一套配置。博客中的 category、published、tags 不应该直接复制进技能文件。
遇到这种报错,先退回本文的最小头部,只保留 name 和 description,排除字段不兼容。不同宿主和校验器支持的扩展字段可能不同,不能把某次报错列出的字段列表当作所有版本的统一规范。
能调用,但行为还是很泛
先检查正文是否全是“专业、完整、清晰”这类抽象要求,再看有没有输入范围、执行步骤和验收标准。用“说明每段代码的输入与预期输出”替换“代码要写好”,通常更容易定位效果。
也要检查任务本身是否给出了原文和目标读者。Skill 保存流程,不能凭空补齐任务材料。
修改 Skill 后,文章没有自动变化
技能文件保存的是下一次执行时使用的说明,不是对旧文章持续生效的格式规则。需要重新发起任务,让 Codex 按更新后的要求处理指定文章,再检查结果。
8. 什么时候值得继续扩展
先让一个小范围的技能反复可用,再增加能力。对本文的示例来说,下一步可能是加入博客 frontmatter 的检查脚本,或者根据自己真实采用的写作习惯完善参考规则。
如果一条规则只在本次任务适用,就留在本次请求里。如果它在几次重构中反复出现,再收进 Skill。这样维护出来的内容更接近你的实际工作方式,也更容易发现和删除已经过时的要求。
If this article helped you, please share it with others!
Some information may be outdated






