本文分享如何将领域知识封装为AI可执行的“数字助手”，通过四层架构提升分析效率与输出稳定性，实现团队知识沉淀。
核心内容：
1. Skill的本质与四层分离架构设计
2. 从使用到开发的关键技巧总结
3. 实战案例分析与团队赋能价值

本文以作者从传统数科向 AI 数科转型的实践为背景，系统阐述了 QoderWork Skills 的开发方法论与工程体系。文章指出 Skill 本质是将领域知识、标准流程及避坑指南封装为 AI Agent 可执行的“数字助手”，并提出了由编排层（SKILL.md）、参数层（config.yaml）、实现层（scripts/）和知识层（references/）构成的四层分离架构，强调通过结构化指令而非单纯代码注入来提升分析效率与输出稳定性。通过对比 Follow Builders 和 Frontend Slides 等案例，以及用户洞察报告、AB 实验分析等自研 Skill 的实战经验，文章总结了 Description 定义、流程编排、配置模板化及渐进式披露等关键开发技巧，旨在通过工程化手段实现团队知识沉淀与标准化，解放人力以聚焦高价值业务决策。

▐  Skill.md 的定位：编排者而非执行者

• 核心原则：SKILL.md 只负责流程编排和决策指引，不嵌入大段实现代码。

• SKILL.md 应该回答的问题是：

• 这个 Skill 什么时候被触发？（触发条件）

• 分析流程有哪些步骤？（步骤编排）

• 每一步调用哪个脚本的哪个函数？（实现委托）

• 遇到异常情况如何决策？（判定标准）

• 不应该出现的内容是大段的 Python 代码——那些应该放在 scripts/ 里。

• 建议篇幅：控制在 200 行以内（我的两个 Skill 分别是 170 行和 133 行），过长的 SKILL.md 会稀释重点，Agent 反而可能忽略关键指引。

▐  config.yaml的设计哲学：模板而非表单

这样的 YAML 不是配置模板，而是一份填好的表单。下次做"直播红包实验"或"搜索排序实验"时，这份配置完全不适用。

正确的做法——参数结构定义模板：

• 设计要点：

• auto 占位符：表示该字段由 scripts/ 中的自动检测逻辑在运行时填充

• 空列表 [ ]：表示该配置项的结构已定义，但具体值在每次运行时动态决定

• [默认值] 标注：有合理默认值的参数（如 significance_level: 0.05）可以直接填入

• 注释说明每个字段的含义、标注 [必填]/[自动检测]/[默认值]

▐  scripts/ 的价值：复杂逻辑的归宿

• Agent 擅长写简单的代码片段，但对于需要精确控制的复杂逻辑（统计检验方法选择、字段自动检测、图表样式），让 Agent 每次临场发挥是不可靠的。

• scripts/ 的作用是把这些关键逻辑固定下来，确保每次执行结果一致。

• 以 AB 实验中的字段自动检测为例：

• 这个函数覆盖了常见的几十种列名变体，保证无论数据来自哪个系统，都能高概率自动映射成功。如果靠 Agent 每次自己猜，准确率和一致性都无法保证。

▐  references/ 的作用：知识的渐进式披露

• SKILL.md 篇幅有限，不可能把每个统计方法的原理都写进去。references/ 提供了渐进式披露（Progressive Disclosure）：

• SKILL.md 只说「连续型指标用 Welch's t-test，非正态时回退到 Mann-Whitney U」

• references/statistical_methods.md 详细解释为什么选 Welch 而非 Student、效应量怎么计算、多重比较校正的原理

• 这样 Agent 在正常执行时读 SKILL.md 就够了；当用户追问"为什么用这个方法"时，Agent 可以引用 references/ 中的详细说明。

• 对比上述设计理念

• 所以核心区别并不是"架构不同"，而是：

1. 没有 config.yaml，配置极简化。 这个Skill的frontmatter只有 name 和 description 两个字段，所有复杂的用户偏好（语言、频率、投递方式）都在首次运行时通过对话生成，存到 ~/.follow-builders/config.json。

2. 【知识层】被解构了。 传统Skill把参考资料统一放在 references/，这个Skill把它拆成了三种不同形态——prompt模板（给AI的指令）、JSON feed（给脚本的数据）、config（信息源列表）。

3. 多了一个“中心化数据服务”。 这是这个Skill最独特的地方：它不要求用户自己配API key去抓推文和播客。作者在GitHub上设了一个每天自动运行的GitHub Actions流水线（.github/workflows/generate-feed.yml），用自己的 X API key 和 Supadata key 抓取数据，结果提交为仓库里的 feed-*.json 文件。用户端的 prepare-digest.js 只需从 GitHub raw URL 拉取这些JSON即可。

▐  Frontend Slides

• 实际文件结构

• 对比上述设计理念

• 分层拆解值得学习的部分

1. 核心设计理念： 作者把 AI 当作一个会遗忘、会走捷径、会趋于平庸的处理器来编程，所以在关键决策点反复设置冗余校验。

2. 几个值得学习的技巧：

1. “NON-NEGOTIABLE”标注法。 第 16 行写 “Viewport Fitting (NON-NEGOTIABLE)”，然后在第 39-48 行展开规则，第 49 行再强调“read viewport-base.css and include its full contents”，第 62 行兜底“Never cram, never scroll”。同一条铁律在文件中出现了 4 次不同表述——这不是啰嗦，而是对抗 AI 在长上下文中注意力衰减的工程手段。

2. 反模式清单。 第 19-35 行不只说“要做什么”，还显式列出“不要做什么”——overused fonts（Inter、Roboto、Arial）、cliched color schemes（purple gradients on white）、predictable layouts。这是给 AI 设置负向约束，因为大模型的“模式坍缩”倾向会让它总是输出最高频的组合，必须显式阻断。

3. 内容密度限制表。 第 53-61 行用一张 6 行的表格，给每种 slide 类型规定了硬性内容上限（比如 content slide 最多 4-6 个 bullet）。

4. “一次性问完”指令。 第 90 行 "Ask ALL questions in a single AskUserQuestion call"。作者深知多轮交互的成本（用户流失、上下文漂移），把 Phase 1 设计成一次性收集所有信息的“表单”。

5. Gotchas 前置。 Phase 6 把部署和导出的“坑”直接写进了 SKILL.md，而不是放在脚本注释里。这意味着 AI 在决定是否调用脚本之前就知道可能出什么问题，能主动提醒用户。

1. 原因在于：配置的本质是“提前固化的决策”。但这个 skill 的所有决策都是运行时通过对话收集的——用户的 mood、slide 数量、内容类型，在 Phase 1-2 实时确定，不存在“提前配置”的场景。

2. 传统 config 层的功能被“溶解”到了三个地方：用户对话（Phase 1-2 收集的偏好，相当于“运行时配置”）、STYLE_PRESETS.md（12 套预定义风格，相当于“枚举型配置”）、viewport-base.css（硬性约束，相当于“不可配置的常量”）。

3. 对比 follow-builders：它需要 config 是因为用户的追踪偏好（语言、频率、投递方式）是跨会话持久化的。而 frontend-slides 每次生成演示文稿都是独立的一次性任务，用完即走，天然不需要持久化配置。

3)第三层：实现层 — scripts/

1. 核心功能（从零生成 HTML 幻灯片）完全不依赖任何脚本——它只靠 SKILL.md 编排 + 知识层的 4 个文件就能工作。

2. 脚本层是纯粹的“可选服务”。extract-pptx.py 只在PPT 转换时调用，deploy.sh 只在用户选择部署时调用，export-pdf.sh 只在用户选择导出 PDF 时调用

3. 当你的“实现层”是 AI 本身时，传统的【 scripts/ 】角色会缩小。 follow-builders 需要 JS 脚本来做 API 调用和数据处理，因为这些是确定性逻辑。但 frontend-slides 的核心任务（生成 HTML/CSS/JS 代码）恰好是 AI 最擅长的事，不需要外部脚本来辅助。

4)第四层：知识层 — 4个文件的精妙分解

1. 没有 references/ 子目录，4 个知识文件直接和 SKILL.md 平级放在根目录——因为 Markdown 的 [file](file) 链接语法在同级目录最简洁，减少路径出错的可能。

2. 4 个文件按关注点分离，各自回答一个不同维度的问题：

   
   

   
   

   • 给代码不如给流程

   
   

   • Agent 本身很擅长写代码，但不擅长把控现实商业世界里的专业数据分析流程。

   • SKILL.md 的职责不是"怎么写 Python"，而是"分析应该包含哪些步骤、关注哪些指标、注意哪些陷阱"，具体实现交给 scripts/。

   • 因此我觉得，SKILL.md的编写是重中之重，至于需不需要给 scripts/，可以具体情况具体分析，但真的都还ok。

   
   

   • 模板比自由发挥更可控

   
   

   • 定义结构化输出的Schema，Skill一定要有能结构化输出的能力，没有Schema，Skill就会退化成和对话聊天一样的背景板

   • 提供明确的报告模板，确保输出格式统一，减少 Agent 的随机发挥带来的不确定性。

   
   

   • config.yaml 是模板不是表单

   
   
   • 所有和具体业务相关的值（实验名称、指标列表、字段名）都不应该写死在 config 里，而是用 auto 或空值占位，运行时由检测逻辑或用户确认来填充。
   
   

   • 控制篇幅， 渐进式披露控制信息密度

   
   

   • SKILL.md 建议控制在 500 行以内 (200行以内更佳)。信息太多反而会稀释重点。

   • SKILL.md 言简意赅，方法论细节放 references/，代码实现放 scripts/。这样 Agent 不会被信息过载。

   
   

   
   

   ▐  关键收获

   
   

   1. 测试数据很重要，测试驱动开发：开发 Skill 时一定要用模拟数据跑通全流程，对 Skill 不断进行测试，发现其中的问题，进一步调整优化，这一步的工作可能占据了实际Skill 开发的70%-80%。

   2. 产运视角 ≠ 数科视角：报告模板要考虑非专业背景用户的阅读体验。“p=0.023”对产运没有意义，“实验组 GMV 提升 8%，建议推全”才是他们想看的。

   3. 工程化思维：Skill 开发不是写一个 Markdown 文件的事，而是一套工程体系。config.yaml 如何设计、scripts/ 如何拆分、SKILL.md 如何引用——这些架构决策直接影响 Skill 的通用性和可维护性。

   4. Token 消耗：对 Skill 进行调用测试验证的过程中，对于Token的消耗量极大，后续需要进一步思考如何在开发过程中节约成本。

   
   

   

   结语

   
   

   • QoderWork Skills 的核心价值在于把团队的分析方法论 & 典型场景/问题产品化。对于数科团队来说，这不仅是效率工具，更是知识管理和标准化的载体。

   • 一个专业的 Skill 不是一个 SKILL.md 文件，而是 SKILL.md（编排）+ config.yaml（参数）+ scripts/（实现）+ references/（知识） 四层协作的工程体系。当然，很多情况下，一个 SKILL.md 文件就能work。这样的架构既通过脚本层的管理实现了可控性&稳定性的工程思维，又通过知识层的管理体现了渐进式加载、渐进式披露的上下文管理美学。

   • 从 Idealab 的 Prompt + RAG 实践，到 QoderWork Skills 的开发，我最大的体会是：AI 的天花板取决于你注入的领域知识质量。技术能力可能已经不再突出化的重要，取而代之的是思维能力、推理能力、产品能力、Business Sense 和 Ownership。

   • 传统数科向 AI 数科的转型，不是让 AI 替代我们，而是让我们把精力从重复性的“跑数出图出报告”中解放出来，聚焦到更有价值的“定义问题、设计方案、推动落地”上。