给 KuroNotes 写一个博客写作 skill：从能用到好读的全过程

背景#

在搭 KuroNotes 的过程中，我越来越清楚地意识到一件事：很多值得写进博客的内容，其实不是在“准备写文章”的时候出现的，而是在一次次技术讨论里慢慢成形的。

比如我们刚刚聊完一个工作流设计、某个页面的调整方式，或者一次具体的技术取舍，往往背景、问题、方案和结论都已经差不多说清楚了。这时候真正缺少的，不是内容本身，而是一个足够顺手的入口，能把这段讨论及时接成一篇草稿。

所以这次我想做的，并不是一个泛用的写作助手，而是一个专门服务 KuroNotes 的 skill：当我说“把刚刚我们讨论的问题记到博客里”时，它能直接帮我整理出一篇可以继续修改的博客草稿；当我说“把更新的内容发布出去”时，它再走构建验证和发布流程。

第一版想解决的问题#

如果只看表面，这个需求像是在给博客增加一个“快捷记录”能力；但真正想解决的，其实是从“讨论完成”到“内容沉淀”之间那一步经常断掉的问题。

很多讨论其实已经很接近文章了，却还是没有进入博客，通常不是因为它们不值得写，而是因为还得再从空白页开始整理一次。只要这一步不够顺，内容就很容易继续停留在聊天里。

所以这个 skill 的第一版，目标被刻意收得很窄：

把最近讨论的一个明确主题整理成博客草稿
在确认之后，再把更新发布出去

这个范围看起来不大，但它刚好覆盖了最常用、也最容易真的被用起来的那条路径。

最小可用版是怎么定下来的#

第一步其实是先把工作流边界定清楚。

在这次设计里，有两个决定从一开始就比较明确。

“记到博客里”和“发布出去”必须拆开#

刚整理出来的内容，很多时候还只是草稿状态。标题可能还想再润一下，描述可能还不够准，正文也可能还差一两个关键例子。如果这时候就直接发布，等于把本来应该留在草稿阶段的内容也一起推上去了。

所以更合理的做法是：先生成草稿，再确认发布。这样既保留了自动化带来的顺手感，也保留了写作本身需要的回看和修改空间。

发布前一定要做本地验证#

既然发布是一个单独步骤，那它就应该有一个明确门槛。

对现在的 KuroNotes 来说，这个门槛很简单：先执行一次构建验证。

1
pnpm build

这条规则后来也被直接写进了 skill 里。原因很直接：自动化真正应该减少的是重复操作，而不是跳过必要检查。只有先确认这次更新不会把站点构建搞坏，后面的 commit 和 push 才是有意义的。

Skill 是怎么一步步长出来的#

从实现上看，这个 skill 最开始其实并不复杂。我们先把最基础的规格文档写出来，明确了它的名字、触发方式、草稿流程和发布流程，然后再把这些规则落进 kuronotes-blog-writer 的 SKILL.md 里。

第一版成型之后，它已经可以完成两件核心工作：

根据最近对话生成一篇新的博客草稿
在用户明确要求发布时，先构建验证，再执行 git 提交和推送

从“能用”这个角度看，这一版其实已经达标了。但问题很快也暴露出来了：它虽然能写出一篇结构完整的文章，却还不太像真正会发出去的博客。

第一次写草稿时暴露出的问题#

我们第一次让它把这次 skill 方案写成博客时，得到的内容更像是一份内部说明文。

它的问题并不在于信息缺失，恰恰相反，是因为写得太“全”了：会把一些只对自己操作仓库有意义的细节也带进去；结构虽然完整，但读起来更像在向自己交代流程，而不是在给读者讲一件值得记录的事情。

后来在修改过程中，这些问题被逐渐明确了出来：

文章应该从我的视角出发，只保留真正重要的内容
不要堆太多 list 和 bullet points
小标题要有，但不必每篇都机械套同一套结构
一些只对内部实现有意义的细节，其实没必要写给读者看

这里面最典型的例子，就是类似“新文章固定写入哪个目录”这种信息。它对 skill 自己执行任务当然重要，但对阅读文章的人来说，通常并没有太大参考价值。

参考文章给了我什么启发#

为了把这篇草稿改得更像真正会发出去的开发记录，我们专门找了两篇参考文章来看：

这两篇文章给我的启发，不是某种固定模板，而是一种很明确的写作取向。

首先，它们都会先把“为什么要做这件事”讲清楚，再进入实现细节。这样读者在看到后面的代码、命令或者设计选择时，会自然知道这些内容为什么存在。

其次，它们保留了必要的技术密度，但不会把所有内部操作全都摊开成流水账。真正留下来的，都是能帮助读者理解问题、方案和取舍的细节。

最后，它们都有一个共同点：读完之后，读者是能带走一点东西的。可能是一个实现思路，可能是一种设计判断，也可能是一条可复用的工作流。它们不是只在记录“作者做了什么”，而是在分享“这件事为什么值得这样做”。

Skill 后来补上的写作约束#

也正是因为这一轮反复修改，我们最后意识到：光让 skill 会“生成草稿”还不够，它还需要知道什么样的草稿才算写得对。

所以在后面的更新里，我们把这次总结出来的经验正式写回了 skill 本身，包括：

文章要更像开发记录或技术随笔，而不是内部备忘录
优先写清楚背景、问题、设计思路和关键取舍
技术细节要保留必需的部分，但不要过量
小标题要清晰，但不要机械套模板
bullet points 可以用，但要克制
每篇文章最好都能让读者带走一个可借鉴点

除此之外，我们还把前面提到的两篇参考文章单独整理成了写作风格参考，作为这个 skill 的补充材料。这样以后再生成草稿时，它就不只是“知道要写什么”，还会更明确地知道“应该写成什么样”。

这次过程里最有价值的经验#

回头看，这次做 skill 最有意思的地方，并不是把一个自动化流程拼起来，而是我们在过程中把“什么样的文章才值得留下来”这件事也一起想清楚了。

最开始的问题像是工具问题：怎么把讨论快速记到博客里。做到后面，它慢慢变成了写作问题：什么样的沉淀，才不是聊天记录的简单搬运，而是真正对自己和读者都有价值的开发记录。

这也是为什么后面 skill 的重点，不再只是“生成 Markdown 文件”，而是“生成一篇更容易阅读、技术细节克制、并且有参考价值的草稿”。

我觉得这一步其实很关键。因为对于个人博客来说，真正稀缺的不是把内容写到文件里，而是把内容写成别人愿意读、自己以后也愿意回头看的东西。

结语#

到现在为止，kuronotes-blog-writer 还是一个很小的 skill，但它已经把一条我很想要的工作流接起来了：讨论完一个问题，可以顺手生成草稿；确认之后，再经过构建验证发布出去。

更重要的是，这次它不只是长出了一个能用的工具，也顺手沉淀出了一套更适合 KuroNotes 的写作标准。以后再让它“把刚刚讨论的问题记到博客里”，目标就不再只是留下记录，而是留下更像真正博客文章的开发记录。