我的Skills开发流程已经开源，欢迎小伙伴们点赞、收藏哈，谢谢！

概览

• 本文深入探讨 Skills 的本质与工程设计方法，分享从实践总结出的系统化开发流程
• 对比 Skills vs Packages 的异同，明确技能化开发在 AI 时代的定位与价值
• 以”系统文献综述”为例，拆解长流程技能的四步工程化设计法
• 介绍三大基础技能（init-project、install-bensz-skills、auto-test-skill）及其在地基性作用
• 阐述从 Skill 到 Pipeline 的进阶路径，以及技能开发的最佳实践

前言

因为在PackyCode的小群里有小伙伴比较好奇Skills这种产品形态，刚好最近几天我也了解并深入地实践了一下，颇有经验。这篇文章，我想聊聊：Skills 到底是什么？我平时怎么设计一个 Skill？如何基于一个 Skill 再往上搭一条”可重复跑”的 Pipeline（工作区级流程）？这篇文章会以我自己做的”系统文献综述”相关实践为例，分享我踩坑后总结出来的一套大致步骤和经验。另外，这个流程同样适用于 OpenAI Codex：现在 Codex 和 Claude Code 都已能按 Agent Skills 的方式发现和调用技能，”写一次，到处用”是可以做到的。(～￣▽￣)～

AI时代的哲学

在深入 Skills 工程化之前，我想先聊聊在 AI 开发实践中沉淀下来的一些”哲学思考”——这些经验教训直接塑造了我后面要讲的设计原则。

小伙伴可能会问：AI 这么强，还需要流程吗？我觉得不但需要，而且更重要。关键是要搞清楚：AI 开发的成功关键不在于”一次性做出完美结果”，而在于”可复现性、可维护性”。

首先是人类角色的重新定位。不要想着让 AI 自动优化流程——我试过，基本上没有好结果。模型总会以一种你意想不到的方向和复杂度工作。人类对项目的全局把握还代替不了，所以我建议：用 AI 辅助提出开发计划，然后人类深度优化这个计划，确定好全局框架后，先让 AI 直接跑一次获得 demo，再针对某些部分细细优化。AI 时代需要的人类智能并没有减少，只是从”关注细节”转向了”关注架构、全局”。

其次是混合式开发的必然性。AI 本质上是概率性的，而不是真正具备智能（否则不可能犯那些低级错误）。所以我们必须做”精确端和模糊端分离”：比如在 Skills 开发中，SKILL.md（模糊端，让 AI 理解意图）与 config.yaml（精确端，约束参数）要明确分开。只要缺乏必要的人工审查，技术债是必然的、并且会迅速膨胀——这也是为什么“轻逻辑重测试”比”重逻辑轻测试”更重要：模块化测试可以缓解对上下文窗口的焦虑，也能减少模型幻觉的影响。

最后是流程的本质回归。软件工程在 AI 时代不仅没有失效，反而更重要了。编程不是一种垂直能力，而是通用能力。即使 AI 将来真的拥有了”智能”，它也必须有效使用软件工程才能开发出优雅的程序。AI 应用的成功、长青，关键在于找到非一次性交互型任务，以及必须依赖混合架构的任务——比如我在前面提到的”系统文献综述”，它正是一个典型的”需要 AI 推理能力 + 需要人类设计流程”的混合任务。

经常”瘦身”、不要过度设计、Long-context 如何保证指令遵循和减少幻觉……这些都是我们在实践中不断遇到的问题。但核心始终是：流程不是为了限制 AI，而是为了让 AI 的能力能够稳定、可复现地释放出来。

Skills 是什么？

如果你把 AI 当成一个”协作者”，那 Skill 可以理解成一个 可复用的任务能力包：

• 它不是一段提示词，而是”一套可执行的工作说明 + 可选的脚本/模板/参考资料”。
• 它有清晰的触发语义：通常由 SKILL.md 里的 name/description 决定什么时候该用它。
• 它遵循渐进式加载（Progressive Disclosure）：
• 平时只暴露元数据（便于”发现”）
• 触发后才加载正文（便于”执行”）
• 需要时再去读 references/（便于”补知识/补规则”）
• scripts/ 更像”工具箱”：倾向于直接运行，而不是把源码塞进上下文让模型背诵

我觉得，Skill 是”可维护的操作手册”——你写的不只是”告诉 AI 怎么做”，而是在写”让未来的你、以及任何协作者，都能稳定复现结果”的说明书。

更重要的一点是：Codex 和 Claude Code 已统一遵循 Agent Skills 开放标准。这意味着我们可以采用单一技能库架构——你写的一套技能，可以同时兼容 Codex、Claude Code 及其他支持 Agent Skills 的平台。”写一次，到处用”不再是空话。(～￣▽￣)～

Skills vs Packages：有什么异同？

小伙伴可能会问：这听起来跟传统软件里的 Package（npm 包、Python 包）好像？哈哈，确实有相似之处，但本质差别挺大的。我特意做了一个对比表，方便你快速理解两者的定位差异：

是不是感觉清楚了？(～￣▽￣)～ 简单来说：

• Package 是给机器跑的，追求”精确执行、性能优先”
• Skill 是给 AI 读的，追求”灵活理解、稳定复现”

两者不是替代关系，而是互补关系——你完全可以在一个 Skill 里调用 Package 提供的脚本工具，这也是我为什么强调 scripts/ 要像”工具箱”一样设计的原因。

为什么必须有一个专门的 Skills 工作区？

很多人一开始会想：我直接把技能丢到 ~/.claude/skills 或 ~/.codex/skills 不就好了？

理论上可以，工程上我强烈不建议。原因很简单：系统目录应该是“部署态（runtime）”，而不是“开发态（workspace）”。

一个专门的 Skills 工作区至少解决三类关键问题：

• 版本与迭代：你需要 Git 来追踪改动、写 Changelog、做回滚；系统目录不适合做这些事。
• 可测试：一个靠谱的 Skill 必须在真实实例里反复跑通；“开发/测试/部署”不分离，很快就乱。
• 可复制安装：你的 Skill 要能被 Codex/Claude Code/其它兼容平台稳定发现，最好是“复制安装”而不是软链接/临时路径魔法。

下面这个目录是我的skill开发区的部分预览。我会把整个技能库当成一个工程项目来维护：

pipelines/skills/
├── Prompts.md                 # 工作流/标准（更像“项目总纲”）
├── AGENTS.md                  # 这个工作区的工程指令
├── init-project/              # 基础 skill：一键生成项目指令
├── install-bensz-skills/      # 基础 skill：系统级安装器（复制部署）
├── auto-test-skill/           # 基础 skill：测试驱动迭代
└── systematic-literature-review/
    ├── SKILL.md               # 核心：语义接口 + 工作流
    ├── README.md              # 面向使用者：怎么触发/怎么写需求
    ├── config.yaml            # 可配置参数（避免硬编码）
    ├── references/            # 需要时再读的规则/模板说明/领域知识
    ├── scripts/               # 可执行脚本（确定性、可重复）
    ├── test/                  # 测试会话（回归用）
    └── CHANGELOG.md           # 有机整体更新的变更记录

一个 Skill 怎么“工程化”设计？

这里我用 systematic-literature-review 这类”长流程、强交付”的 Skill 举例，因为它最能体现 Skill 的工程价值。

systematic-literature-review 是我设计的一个自动化做系统综述/文献综述的 AI 技能。你可能会问：”这不就是个文献搜索吗？”差别可大了去了！它做的事情远不止”搜搜论文”：
– 自动定检索词 → AI 自行决定用哪些关键词去哪里搜（PubMed/arXiv/Google Scholar/多源检索）
– 智能筛选 → 逐篇读摘要、智能打分（1-10 分语义相关性）、做子主题归类、按高分优先比例选文
– 自动规划字数预算 → “综/述”字数分配（70% 引用段 + 30% 无引用段），三次采样取均值
– 全自动写作 → 固定骨架（摘要/引言/子主题/讨论/展望/结论），保留正文字数与参考文献数的硬校验
– 强制导出 → PDF + Word 双格式，支持多语言翻译（中英日德法西等）

最关键的是：它是完全可重现的——从检索词到参考文献列表，从字数统计到引用一致性，每一步都有日志可追溯。是不是有点像”把整个综述流程当 CI/CD 管道跑”？(〜￣▽￣)〜

第一步：先设计”语义接口”，再写实现

我会把 SKILL.md 的 YAML 头部当成“技能的 API 文档”，至少想清楚两件事：

• 做什么：核心能力一句话讲清（比如系统综述、相关工作、文献调研）。
• 何时用：触发场景写进 description，让工具能“自然匹配”到它。

你可能会问：为啥这么在意 description？
因为在实际使用时，很多时候你不会精确地说“请调用 XX skill”，你会说“帮我做个文献综述”。这时候描述就是路标。

第二步：把工作流拆成“可验证的阶段”

我做系统综述时最怕两件事：中途崩和产出不可验。所以我会把流程拆成一组“阶段”，每个阶段都尽量做到：

• 有明确输入
• 有明确输出文件
• 可以单独重跑
• 失败时能定位问题

以系统综述为例，我通常会把它拆成类似这种节奏（只讲结构，不讲具体实现）：

• 多查询检索 → 统一候选集 → 去重
• 标题/摘要相关性评分（并做子主题归类）
• 按策略选文（例如高分优先 + 覆盖多子主题）
• 规划写作预算（比如“引用段/非引用段”的比例预算）
• 正文写作（固定章节骨架：摘要/引言/子主题/讨论/展望/结论）
• 硬校验与导出（LaTeX+BibTeX、PDF/Word、引用一致性等）

核心思想是：把“我觉得写完了”变成“机器能验收”。

第三步：把“易碎点”变成“护栏”

长流程技能一定会遇到各种意外（路径不对、模板缺失、恢复状态异常、LaTeX 编译失败、引用 key 对不上……）。

我自己的经验是：不要指望模型每次都聪明，应该在 Skill 里提前写好“护栏策略”：

• 恢复/续跑时先做路径自检：宁愿清理重来，也不要把错误状态一路传下去。
• 关键产出做硬门槛校验：字数范围、参考文献数量、必需章节、\cite{} 与 .bib 对齐等
• 输出可追溯的日志/报告：让你能事后快速复盘”这次为什么不行”

是不是感觉有点像“把 AI 当 CI 用”？对，就是这个味儿。哈哈。

第四步：把“给用户用”与“给维护者用”分开

我会强制自己做两份文档：

• README.md：面向使用者——怎么触发、怎么提需求、怎么选档位/范围。
• SKILL.md：面向执行者（AI）——工作流、输入确认、输出规范、校验规则。

这样做的好处是：你未来要改内部流程时，不一定要让用户跟着改提示词，而用户提需求也不会被一堆工程细节劝退。

三个基础 Skill：为什么它们是整个体系的地基？

我做了一段时间后发现，真正能让 Skill 体系跑起来的，不是某个“很强的业务 Skill”，而是这三个“基础 Skill”。它们分别解决：初始化、部署、迭代。

init-project：一键生成项目指令（AGENTS.md / CLAUDE.md）

只要你会经常开新工作区（新仓库、新 pipeline、新专题），你就会懂：让 AI 一上来就“懂规矩”太重要了。

init-project 的意义在于：

• 自动分析当前目录，大致判断项目类型/用途
• 生成统一风格的 AGENTS.md / CLAUDE.md
• 把工程原则（KISS/DRY/YAGNI/关注点分离等）固化成“默认行为”

对我来说，它等价于：把“我想要的协作方式”变成可复制的模板。

install-bensz-skills：系统级复制安装（让 Skill 真正“可用”）

我不喜欢软链接式的“临时可用”，我更想要一种“装上就能用、换目录也能用”的体验。

install-bensz-skills 做的事情很朴素但很关键：

• 把 pipelines/skills/ 下的技能复制安装到系统目录
• Codex：~/.codex/skills/
• Claude Code：~/.claude/skills/
• 用“版本指纹”（例如基于 SKILL.md 的哈希）来决定是否需要更新，只安装变化的部分

它的意义在于：你可以把技能库当成“源码仓库”，把系统目录当成“运行环境”，这就是标准的开发/部署分离。

auto-test-skill：测试驱动迭代（把”修修补补”变成可追溯的优化循环）

Skill 的迭代很容易变成：用户提一句，你改两行，过两天又坏了……

我后面就专门做了一个 auto-test-skill，用来强制自己按”测试会话”管理迭代：

• 先把问题整理成结构化报告（Bug 清单 + 优先级）
• 再输出 step-by-step 的优化计划
• 每轮迭代都落到一个时间戳测试目录里（计划/报告/数据分离）

它的价值不是”帮我写测试代码”，而是帮我建立一种习惯：每次改动都能解释、能复现、能验收。

从 Skill 到 Pipeline：为什么还要单独做 Pipeline 工作区？

Skill 解决的是”如何完成某个小任务”。而我抽象出的 Pipeline，它的作用是处理”任务如何被组织、如何被重复执行、如何不互相污染”这一问题。

我还是以写文献综述（下称 reviews）为例。我把 reviews 设计成一个”综述项目工厂”，它只做三件事：

• 目录命名与隔离：每个项目一个目录（例如 {主题}），互不干扰
• 强制依赖某个 Skill：比如规定做综述必须调用 systematic-literature-review，并且必须传 --work-dir，否则直接失败
• 只定义组织规则，不复制技能细节：Skill 会进化，Pipeline 不要把 Skill 的规则抄一遍，否则很快就”前后不一致”
• 可扩展性：以后有机会还可以接入其它 Skill

可以这么理解：Skill 是“工位上那台机器”；Pipeline 是“工厂的车间管理制度”。

Skill 开发的最佳实践

如果你想从 0 做 Skill + Pipeline，强烈建议基于我的 huangwb8/skills 项目开发（已搭建好完整的工程结构和基础技能，可直接 fork 或参考）。大致步骤如下：

假设 Skill 的工作区是 skills

• 提一个简单的需求，让 AI 制定计划（注意，是计划而不是一下子落地）。AGENTS.md 和 CLAUDE.md 文件已经规范了 AI 的行为，它会自动生成规范的目录结构。
• 审查 AI 的计划。这一步不要偷懒。这是必须的，根据我的经验。两个作用：1. 你要知道 AI 在干什么 2. AI 干得不对你可以说
• 然后不断地迭代，直到计划比较完美
• 让 AI 落地，并且跑轻量的测试（你甚至可以像我一样，设计一个 auto-test-skill 管理迭代：问题→计划→修复→复测→写验证报告）。如果你胆子大，要用 auto-test-skill 自动优化项目，我建议还是用 GPT-4.1 和 4.5-Opus 这种比较智能、长上下文的模型来跑。我是喜欢自己看，因为这会让我对项目的发展有足够的把握度和安全感。
• 验收结果，查看测试报告
• 不断迭代，获得 skill 的初版
• 跑实例。在实例的经验和错误中不断学习（基于 AI）。auto-test-skill 又来了
• 将 skill 发展到符合预期为止

是不是感觉一下子”工程味”就上来了？这就对了：Skill 体系的关键不是聪明，而是稳定。我觉得，Vibe coding 时代如果你能习惯做一个”经常有全局思维且仅偶尔关注细节”的人，那么 Claude Code/Codex 用起来一定是很爽的。

小结

你现在最想把哪类工作做成 Skill？我也想看看大家都在”自动化”什么。如果你也在做类似的工程化探索，欢迎评论区或 GitHub Issues 里留下你的想法吧！