这篇文章是对一次真实 Codex 协作过程的复盘。
最开始，我只是想创建一个“写博客并一键部署”的 Skill。真正做下来以后，才发现这个需求并不只是写一段提示词，而是要把写作、配图、构建、预览、源码保存、静态页面部署这些动作串成一条可靠的发布流水线。
这也是我对 Skill 最重要的理解：
Skill 不是让 AI 记住几句口号，而是把一次真实任务里的项目经验、操作顺序和风险边界沉淀下来。
一、需求从一句话开始
最初的需求很简单：
我现在需要创建一个写博客并一键部署的技能。
如果直接让 AI 写一个 Skill，很容易得到一份很泛的说明，比如“帮用户写高质量博客”“遵循最佳实践”“部署前检查”。这些话没有错，但对真实项目帮助有限。
因为这个博客项目有自己的上下文：
- 它是 Hexo 博客
- 文章放在
source/_posts/ - 图片资源有项目内约定
- 部署页面用 GitHub Pages
- 源码仓库和页面仓库不是同一个
- 部署前必须让用户预览确认
所以第一步不是写 Skill，而是先观察项目。
二、先从项目事实里提炼规则
在当前仓库里，几个文件给出了关键线索：
1 | package.json |
package.json 说明了基础命令：
1 | { |
push.sh 说明了已有部署习惯：
1 | hexo clean && hexo g && hexo d |
_config.yml 说明这是 Hexo 6 项目，文章目录是 source/_posts/，并且配置了 GitHub Pages 部署仓库。
这些信息决定了 Skill 不能写成通用博客助手，而应该写成当前项目专属的发布助手。
三、先计划，再实现
在写 Skill 之前，先确认了几个关键决策：
- Skill 放在当前仓库的
skills/目录 - 默认服务这个 Hexo 博客，而不是全局泛用
- 写作采用“先大纲后成文”
- 部署不能自动跳过确认
- 一键部署也必须保留安全门槛
于是创建了：
1 | skills/hexo-blog-publisher/SKILL.md |
SKILL.md 的 frontmatter 负责让 Codex 知道什么时候触发它：
1 |
|
这里的 description 很关键。它不是给人看的宣传语，而是给 Codex 判断“这个请求是否应该加载该 Skill”的触发条件。
四、第一版 Skill 做对了什么
第一版 Skill 已经包含了几个正确方向：
- 写博客前先确认标题、大纲和标签
- 新文章默认放到
source/_posts/ - frontmatter 使用
title、date、tags - 修改文章后运行
npm run build - 部署前需要用户明确确认
- 部署命令使用
hexo clean && hexo g && hexo d
这已经比普通提示词可靠很多。
但真正执行一次完整流程后，问题也暴露出来了。
五、真实执行时暴露的问题
1. 图文结合应该更早进入流程
第一次写文章时，我先生成了纯文字版本。后来提醒“最好图文结合”，才补了一张流程图。
这说明 Skill 里应该提前考虑内容形态。对于教程、复盘、流程类文章，配图不是装饰，而是帮助读者理解结构的关键部分。
2. 图片目录不能只凭 Hexo 配置判断
项目里虽然开启了 post_asset_folder: true，但实际构建时，文章同名 .assets 目录里的 SVG 被插件改成了异常路径：
1 | /.top//codex-skill-workflow.svg |
构建本身没有失败，但生成后的页面图片路径是错的。
最后改成把图放在：
1 | source/images/codex-skill-workflow.svg |
并在文章里引用：
1 |  |
这才通过了 HTML 和资源检查。
这件事提醒我：Skill 里的规则不能只看配置文件，还要吸收真实执行中的反馈。
3. 部署前应该先预览
第一次执行“一键部署”时，虽然构建通过，也成功发布到了 GitHub Pages，但顺序并不理想。
更正确的顺序应该是：
1 | 写文章 -> 加图 -> 构建 -> 检查 HTML 和图片 -> 本地预览 -> 用户确认 -> 提交源码 -> 部署页面 |
也就是说，用户应该先看到本地预览，再决定是否提交和部署。
4. 部署页面不等于保存源码
Hexo 部署到 GitHub Pages 的仓库里，保存的是生成后的静态页面。真正可维护的内容是当前源码仓库里的：
- Markdown 原文
- 图片源文件
- Skill 文件
- Hexo 配置
- 主题和脚手架
所以发布完成不能只看 GitHub Pages 是否更新。源码仓库也必须提交并推送，否则以后就只剩线上页面，没有可维护源头。
六、Skill 被迭代成发布 Runbook
根据这些问题，hexo-blog-publisher 被继续优化，不再只是“写作和部署说明”，而是变成了一份发布 Runbook。
它现在的核心流程是：
1 | 写作/改稿 |
这个顺序里最重要的是两个门槛：
- 预览确认前，不提交源码
- 源码保存前，不把发布视为完成
七、区分源码仓库和页面仓库
这次实践里，一个很关键的认知是：博客发布至少涉及两个仓库。
源码仓库是当前博客项目，远端在公开文章里应该脱敏成类似这样的占位：
1 | https://example.com/<user>/<blog-source-repo>.git |
它保存的是可维护内容。
GitHub Pages 仓库是 Hexo 生成后的静态站点仓库，公开记录时也不应该暴露真实账号和仓库名：
1 | git@example.com:<user>/<pages-repo>.git |
它保存的是部署产物。
两者角色不同：
| 仓库 | 保存内容 | 作用 |
|---|---|---|
| 源码仓库 | Markdown、图片、Skill、配置 | 后续维护和继续写作 |
| GitHub Pages 仓库 | HTML、CSS、JS、静态资源 | 对外访问的网站 |
只有两个仓库都处理完，发布才算闭环。
八、最终的完成定义
优化后的 Skill 里加入了 Done Definition。
一次博客发布只有同时满足这些条件，才算完成：
- 文章已经本地预览
- 用户明确确认预览没问题
- 源码变更已经提交并推送
- GitHub Pages 静态页面部署成功
- 当前源码仓库
git status --branch --short是干净的 - 最终回复里报告源码 commit 和部署结果
这个完成定义很有用。它让“一键部署”不再只是一个命令，而是一条有收尾检查的流程。
九、我学到的 Skill 生成方法
这次过程可以总结成一个通用方法：
- 不要直接空写 Skill，先观察项目
- 从真实配置、脚本、目录结构里提炼事实
- 先把用户目标拆成流程
- 明确哪些动作可以自动做，哪些动作必须确认
- 做一次真实任务，让问题暴露出来
- 把踩坑结果反向写回 Skill
- 给 Skill 加完成定义，而不只是操作步骤
一个好的 Skill 应该不断吸收实战反馈。
如果第一次生成的 Skill 只是“能用”，第二次迭代后的 Skill 才开始变得“可靠”。
十、当前这套博客发布 Skill 的价值
现在这个 Skill 能解决的不只是“帮我写文章”。
它真正沉淀的是一套博客发布习惯：
- 写之前先确认方向
- 教程类文章优先考虑图文结合
- 图片放到当前项目已验证的
source/images/ - 构建后检查 HTML 和资源
- 发布前先本地预览
- 预览后等用户确认
- 保存源码仓库
- 再部署 GitHub Pages
- 最后检查源码状态
这套流程比单纯的“hexo d”慢一点，但更稳。
尤其是当 AI 可以直接读写文件、执行命令、推送远端时，慢一点的确认门槛反而是必要的。
总结
这次从一句“创建一个写博客并一键部署的技能”开始，最后得到的不只是一个 hexo-blog-publisher Skill，而是一套经过真实发布验证的工作流。
我最大的收获是：
Skill 的价值不在于把提示词写长，而在于把项目事实、执行顺序、失败经验和完成标准写清楚。
当这些内容沉淀下来，下一次再写博客、预览、提交源码和部署页面，AI 就不会只是“帮忙执行命令”，而是能按这个项目真正需要的方式完成整套闭环。