发布日期：2026-10-24
阅读时间：约 11 分钟
分类：技术杂谈
专栏：未归档
关键词：
AI 编程SkillAgent协作开发者工具知识沉淀
作者导读 ：过去半年我业余写了 18 个 Skill，从"一份简历底稿衍生二十几份岗位副本"这种小需求，一路做到"生成能被git apply干净应用的补丁"这种工程细节。我一直以为自己只是单纯搞出一些文档，直到后来边踩坑边修skill，那一刻才意识到：我写的不只是"小工具"，更是"基建设施"。本文我将回顾这些 Skill 的由来，交代它们如何从个人提效工具沉淀为可复用的 AI 编程基础设施，并讨论这一转变对未来开发协作模式的影响。
一、起点：一份简历，二十几份副本
第一次认真写 Skill，是 2026 年 7 月在 WorkBuddy。
起因很具体：投简历，同一份 docx 底稿要针对不同岗位衍生出十几份副本------前端、后端、测试、产品、咨询、需求分析，各不相同，还得按岗位细则微调。约束还锁得很死：排版不能变（字体、图片、段间距、表格结构一律不动），还得控制篇幅压进 A4 一页。
就这样，"排版不变""控制篇幅"这四个字，把这件事从"改文案"变成了工程问题。
于是有了 resume-jd-copy：读底稿现状、量真实渲染高度、只改某几个目标单元格、压到一页、校验锁区未被动。169 行的 SKILL.md，写清了每一处"不要假设"。复利来得很快：换岗位只换一套 spec 字典，脚本不再改动。那一刻我隐约意识到：写下来的不是提示词，是一条可复用的流水线。
二、转折：踩坑比一帆风顺更有价值
真正让我改变想法的，是一个具体的坑，它出在排版测量上。我原本以为页数可以靠字符总数估算------首版 1775 个字符，渲染出来果然是 2 页。可精简到约 1580 字符，页数却变成 1 页，填充率 94.7%。字数"差不多"，页数不同。
根因是后来才想明白的：段落一旦超过约 50 个字就会换行，而换行等于该段行成本翻倍。决定页数的从来不是字符总数，而是有多少段被折了行。
这个坑让我意识到一件事，起初并未想透：流程可以重新推导，踩坑难以精准预计。 "页数与字符数成正比"问一遍搜索引擎就知道；"段落超过 50 字就翻倍"，除非真实遇到，否则几乎无法推导出来。模型同样不会自动拥有它------这条知识不在任何人的预训练语料里，只存在于我那一次失败里。
自那天起，我写 Skill 的重心便从"记录怎么做"转向"记录哪些路走不通"。这是它们从工具变成基础设施的真正起点，也就有了第四节我们提到的"踩坑清单"。
三、什么才算基础设施：三个标志
并非所有带 SKILL.md 的目录都算基础设施。我给自己划了三条线：
标志一：原作者不在场也能用。 resume-jd-copy 把"一次写作、多次派生"变成了常态：同一份底稿，针对不同岗位只换 spec 字典，脚本不再改动；接手的人不必重写改写逻辑。这已跨过"个人提效工具"的边界。
标志二：有约定，而不是只有描述。 这一点我从 paper-quick-reader 学来------它并非我所写（社区作者的 public Skill），但结构值得借鉴：description 列出触发词与反范围；allowed-tools 圈定边界；正文含一份 NEVER 清单；还有 verify_provenance.py 做页码级溯源校验。对比我早期写的 Skill------一段描述加一个脚本列表------差距十分明显。描述是给模型看的提示，约定是给系统看的保证。 前者说"我希望它这么做"，后者承诺"它保证如此，违反可被发现"。
标志三：能自我校验，而不是自我声明。 这是我最看重的一条。git-patch-verify 的存在意义就是：不要手写 unified diff，让 git 生成，再用 git apply --check 干跑验证。它不承诺"补丁大致无误"，直接判定"能干净应用"或"不能"；它与任何人的任何仓库都无关，换个项目照样能用。
还有一件小事值得说明：agent_created: true 这个 frontmatter 字段。官方 skill-creator 文档是这么定义的------"The YAML frontmatter MUST include agent_created: true so that skill_manage can modify or delete the skill later." 它不是署名，不是标签，而是一把钥匙 ：只有带上这个字段（或已被登记在册），skill_manage 才允许后续修改或删除这个 Skill。
我一开始理解错了，以为它是"这是我和 Agent 一起写的"那种作者标记，可是翻到 CLI 里 validateAgentCreated 的实现才发现，判定只有一条：isInRegistry(name) || hasAgentCreatedFrontmatter(content)，跟"谁写的"毫无关系。但讲清之后反倒更认同自己写下的规则：标记本身必要但不那么重要，能被改 才是重点------它意味着这个 Skill 是持续维护的活文档，而非写完就躺在磁盘上的快照。
四、真正的壁垒，是那份坑位清单
2026 年 7 月 7 日，我差点把大半年攒下的课外学习笔记全搞没。
虽说我对一些公开资料的学习记录采用了 AI 辅助，可是某天我用 python-docx 往 Word 文档中间插入一整段内容时，我用了网上常见的"先追加到末尾、再移动到中间"的写法：记录 body 快照、筛出新元素、remove 后 addprevious。结果 document.xml 被清空------只剩三个空段落，38MB 全是失去引用的 media 图片。文字、表格、图片引用全部丢失，且图片无法从 media 目录恢复，因为它们不知道该放回哪一段。
重建花了两天，救回来靠的是：每一讲的 PDF、提取文本、图片目录、生成脚本都还在。 脚本链能重建文档，但后来手动加进的 18 张图不在任何脚本里，永久丢失------这部分是脚本救不回的。
自那以后我给所有 Word 结构变更定了一条铁律：先插入唯一占位段落作 marker，在其后构建内容，移动时用 kids.index(marker_el) 定位边界（务必排除 sectPr），构建完删掉 marker。
那次事故的真正产物不是一个脚本，是三条写进 Skill 的规则。这三条，对任何没经历过我那份文档的下一个开发者都不可推导。
事故之后，我开始系统盘点所有"工具报告成功、结果未必成功"的时刻，把后来踩的坑逐一补进清单。它们形态、场景各异，却共享同一个现象------"看似正确、实操会出问题"：
- 简历排版。 同一个
resume-jd-copy，还有个更隐蔽的坑：我第一版用 python-docx 的Document(BASE).save()重写表格，它重算了tblGrid列宽，个别单元格多折一行，简历凭空高出十行、变成两页。正确做法是shutil.copy2后用 lxml 直改word/document.xml。 - 批量编辑与追加写入。 并行发多个 Edit 改 24 个代码块，工具全部返回成功，实际有 7 块没落盘；向已存在文件追加时用了
Write而非Edit，直接把 340 行的当日工作日志清空了，搜索后确认无任何备份。对策是：批量改动改用临时 Python 脚本顺序替换，每条assert s.count(old) == 1，改完跑自检核对围栏数、括号配平、覆盖率；追加一律用Edit。不要相信工具的成功返回，要相信自检。
这几条放在一起，构成了一个组织关于"什么东西不能做"的记忆。而这正是模型永远无法自己获得的东西：模型能写出 python-docx 的正确用法，但不会知道我们 7 月 7 日失去了什么；它能生成一个看起来毫无问题的 Document.save()，却不知道那份简历会变两页。
Skill 与 prompt 的分水岭就在这里：prompt 记录"该怎么做"，Skill 记录"哪些路走不通"。 前者可再生，后者不可再生------它是踩坑史的具象化。
五、这对未来的开发协作意味着什么
有两个变化我想我可以确定：
第一，新人的 onboarding 成本第一次有了量级下降的可能。 过去 senior 的经验靠口口相传存在，成本极高且不可检索，如今可以写成一个 @skill。我辅导低年级同学时做过粗略对照：把"这类课外作业该怎么做、常见错在哪"写成 Skill 后，交上来的东西质量明显更稳------不是他们变聪明了，而是"知道标准长什么样"不必等别人示范三遍。（样本很小，不足为证，但方向让我信服。）
第二，组织记忆第一次可版本化。 Skill 进 git，diff 可读，review 可做。这是 prompt 做不到的------它只存在于对话历史里，用完就没了。
顺带说评审维度的变化：代码评审看"这行逻辑对不对"，Skill 评审看"契约的边界描述得准不准、这个坑位清单还成立吗"。前者找 bug，后者找过期------后者要求评审者自己也踩过坑。所以写 Skill 的人必须是真正踩过坑的人。
但必须坦白：从这里往下是我的 extrapolation------从"一个人加一个小团队"的样本往外推，不是业界共识，也未必正确。
同时我也要端出来一盆冷水：Skill 会腐烂，而且比文档腐烂得更快。 因为它绑定了三样会变的东西------模型行为、工具版本、路径环境。有的 Skill 里写着"当前为硬编码死路径"，本质上是给未来的自己埋了一枚时间戳：某天你换了工作目录，"100% 可复现"就变成"100% 报错"。
所以维护 Skill 本身就是工程活。而一旦没人做，一个曾经精确到 assert s.count(old) == 1 的 Skill，半年后就是一具看起来很专业的僵尸：它还会自信地告诉你该怎么做，只是路径全错。
AI 编程的下一个阶段，不是让模型更聪明，而是让"我们知道的事"变得机器可读、可执行、可验证。 这件事没有捷径，须有人真的踩过坑、付过学费、写下来。
六、总结
到 2026 年 10 月，我的用户级 Skill 目录里有 21 个 Skill，其中 18 个是我自己写的，覆盖课外学习、转写、写作、文档等场景，合计约 1.7 万行。限于篇幅，只列最常用的几个：
| 类别 | Skill | 一句话 |
|---|---|---|
| 课外学习 | ai-article-scout |
指定时间窗内全网检索技术文章 |
| 文档 | resume-jd-copy |
同一份简历底稿 → 按 JD 衍生的单页副本 |
| 工程 | git-patch-verify |
机械生成可干净应用的补丁 + 干跑验证 |
外加三个社区的 public Skill：academic-translation、paper-quick-reader、ima-skills------并非我所写，但我从它们的契约设计里学到了不少。
回看这半年，我的身份变过三次：用户 （想省时间）、作者 （想让流程跑通）、维护者 （想让踩过的坑不再被踩第二遍）。第三个身份才是"基础设施"------它不产出新功能，产出的是确定性：让下一个人、下一个 session、下一台机器，不必"再交一次学费"。
这就是从"用 AI 写代码"到"给 AI 建基础设施"的分界线。今天是 1024 ，祝大家写代码时少踩几个坑，多沉淀点能被复用的东西------当然，别让下一个人当你的复读机。
标签 ：AI 编程 Skill Agent 协作 开发者工具 知识沉淀 1024特辑
参考文献
WorkBuddy. (n.d.). Skill Creator: Guide for creating effective skills 内置 Skill 文档.
WorkBuddy. (n.d.). CLI implementation: validateAgentCreated / hasAgentCreatedFrontmatter 源代码.
WorkBuddy. (n.d.). Livestream Poster: 生成直播宣传海报 内置 Skill 示例.
注：第三节引用的 "The YAML frontmatter MUST include agent_created: true so that skill_manage can modify or delete the skill later." 出自上列第一份文档的 "Agent-Created Flag" 段落。
原创声明
本文为作者原创，版权归作者所有。原文于 2026-10-24 同步发布于 CSDN、博客园、稀土掘金、51CTO、知乎。
欢迎学习与分享，但请尊重原创，转载请保留署名与出处。
未经许可，禁止用于商业用途或二次发布。
本文使用 AI 辅助生成，技术细节与事实经作者核实。