如果你之前阅读过我的文章《小白也能解锁 Claude Code 的秘密武器：Skills》的话，那么在 Skills 越来越火热的当下，你或许会抱有以下的疑问：
Skills 不是应该只有一个 Markdown 文件吗？为什么我看别人 Remotion 的 Skills 都有一大堆 Rules 什么之类的！
为什么我 SKILL.md 写的那么长，反而感觉它越来越笨了呢？
我该怎么样做出别人那种特别厉害的 Skill 呀？
假若你曾冒出来过这样的念头，那今天这篇文章，将会彻底解决你的疑问和顾虑。我们将跳出 SKILL.md 的单文件思维，进入“文档架构”的世界。
这期文章篇幅会较长，但无需担心，依旧是小白也能看懂的内容，并且配合马上能上手练习的实战案例，相信你看完后，也能完成属于你的 Skill 作品！
今天我们要讲的是 -- Skills 文档架构。
第一章：为什么你的 SKILL.md 不够用？单文件思维的两大“困境”
在学习任何新技能的初期，我们总是倾向于最简单直接的方法。对于 Claude Code Skills 而言，这意味着把所有东西都塞进 SKILL.md。这在入门阶段完全没问题，但当你试图构建一个真正强大的、可长期使用的 Skill 时，这种单文件思维模式的弊端就会暴露无遗。
困境一：上下文的“无形枷锁”
这个大家都应该知道，当你将所有指令、规则、示例代码、参考文档全部堆砌在一个 SKILL.md 中时，每一次 Skill 的触发都变成了一次沉重的“记忆负担”。Claude 就像一个需要时刻背着一本厚重百科全书的学者，即使只是为了查找一句话，也必须扛着整本书。
这将会导致：
性能下降：加载和处理庞大的 SKILL.md 会消耗更多时间，让交互变得迟钝。
关键信息丢失：当上下文接近极限时，模型可能会“遗忘”掉文件开头或中间的关键指令，导致执行效果大打折扣，出现所谓的“指令漂移”。
预算超支：在某些计费模式下，更大的上下文意味着更高的成本。
困境二：维护的“噩梦迷宫”
一个超过 500 行的 SKILL.md 就是一个维护的噩梦。想象一下，你现在需要更新其中关于“数据库连接池”的最佳实践。你不得不在这个巨大的文本文件中，通过 Ctrl+F 小心翼翼地定位，然后像拆弹专家一样修改内容，同时祈祷不会影响到其他不相关的部分。
这种高耦合的结构，会带来诸多的问题：
逻辑混乱：做到后面，你自己都看不懂自己在做什么
可读性差：就算你能看懂，你的同事想要用，也得掉层皮
修改风险高：原本能跑的，你改完可能就跑不了了
第二章：Skill 2.0的核心 - 像搭乐高一样构建你的“技能”
告别了单文件的混乱，我们迎来的是 Skill 2.0 的核心思想：模块化与渐进式披露（Progressive Disclosure）。这个听起来有点“学术”的词，其实原理非常简单，就像我们日常阅读一本书：
先看目录（SKILL.md）：我们首先浏览目录，对全书的结构有一个宏观的了解。
按需阅读章节（引用文件）：当我们对某个特定章节感兴趣时，才会翻到那一页去深入阅读。
Claude Code 使用 Skill 的方式与此完全相同。它不会一口气吞下所有信息，而是先加载一个轻量的“目录” —— SKILL.md，然后根据任务的需要，通过文件链接去“翻阅”更具体的“章节”——也就是我们拆分出去的各种 .md，.py 或 .json 文件 。
这种架构的精髓在于，将一个庞大的知识体系，拆解成一个个独立、内聚、可管理的“知识积木”。然后，通过 SKILL.md 这个“蓝图”，将这些积木有机地组织起来。这不仅解决了上下文的“无形枷锁”，更让维护、协作和扩展变得前所未有的简单。
👹文档架构的“规则怪谈”如下：
基于这一核心思想，社区和官方的最佳实践中沉淀出了两种最经典、最实用的文档架构模式：知识库型（Knowledge Base） 和 工作流型（Workflow）。
模式一：知识库型架构 （Knowledge Base）
适用场景：当你的 Skill 主要是为了给 Claude 提供一套静态的、结构化的知识时，这种模式是你的不二之选。比如：
公司内部的 API 文档
特定编程框架（如 React, Vue）的最佳实践
团队共享的设计规范或写作风格指南
核心理念：将知识“原子化”。每一个独立的知识点都应该是一个独立的文件，而 SKILL.md 则扮演着这些知识点的“索引”或“目录”的角色。
目录结构：
SKILL.md 怎么写：
工作原理：
当用户问 "公司的 OKR 是什么意思" 时，Claude 会：
先看 SKILL.md，发现这是个术语问题
打开 knowledge/术语表.md，找到 OKR 的解释
回答用户
Claude Code 不会去打开 "产品FAQ" 或 "报销流程"，因为跟当前问题无关。这就是"按需取用"的威力。
⚠️也就是说， 如果 SKILL.md 里面没有提及到需要使用某些文件，某些文件将永远不会被用上！
模式二：工作流模式 -- 打造你的“自动化流水线”
适合场景：当你的 Skill 是要完成一个多步骤的任务时。
典型例子：
写周报（收集信息 → 整理 → 按格式输出）
做会议纪要（听录音 → 提取要点 → 生成文档）
发布文章（检查格式 → 配图 → 发布到平台）
核心理念：将任务“流程化”。把一个复杂的任务拆解成一系列线性的、可独立执行和验证的步骤，每个步骤都是一个独立的文件。
推荐目录结构：
SKILL.md 怎么写：
工作原理：
当用户说"帮我写周报"时，Claude 会：
看 SKILL.md，了解整体流程
依次执行 step1 → step2 → step3
在 step3 时，打开"周报模板"来格式化输出
每完成一步，在清单上打勾 ✓
这就像一条流水线，每个步骤都清清楚楚，不会漏也不会乱！
知识库 vs. 工作流：我该如何选择？
当然，在现实世界的复杂项目中，这两种模式并非完全互斥。你完全可以在一个工作流型的 Skill 中，引入一个 reference/ 目录来存放知识库型的参考文档。
掌握了这两种核心架构，你就拥有了构建任何复杂 Skill 的基础。接下来，我们将进入实战环节，手把手带你从零开始，构建一个既实用又结构精良的 Skill！
第三章：实战演练！10 分钟打造你的第一个“架构化” Skill
理论讲完了，现在我们来实战！我会带你从零开始，用 10 分钟打造一个真正好用的"AI 周报助手"。
这个案例之所以选周报，是因为：
人人都要写周报：不管你是程序员、产品经理还是运营，都能用
效果立竿见影：做完马上就能用，周五下班前再也不用愁了
完美展示架构思想：既有工作流，又有知识库！
💡下面较长篇幅都是模板文件，以供大家 Copy & Paste 体验！大家实操完的结构应该如下：
🔥前几步大家只需要跟着 Copy & Paste 即可，一切感悟都会在“最后一步”为大家打通！
第一步：创建文件夹结构
打开你的终端（或者文件管理器），创建以下结构：
创建完成后，你应该有这样的目录：
第二步：编写“写作规范” （Rules）
这是给 Claude 的"写作指南"，告诉它周报应该怎么写：
第三步：编写"周报模板" ( report-template.md )
这是周报的输出格式，Claude 会严格按照这个模板来生成内容：
第四步：编写工作流步骤
1️⃣ Workflow 第一步：搜集信息 （step1-collect.md）
2️⃣ Workflow 第二步：整理内容 （step2-organize.md）
3️⃣ Workflow 第三步：生成周报 （step3-generate.md）
第五步：编写主控文件 (SKILL.md) ！
这是整个 Skill 的"大脑"，把所有东西串起来：
第六步：见证奇迹！
现在，在确保了 Skills 已经存放在~/.claude/skills/ 目录下后，可以尝试在 Claude Code 中输入：
如果你能在 Claude Code 里面，看到以下画面，那就代表着 Skill 已经存在于你的目录了：
当你输入指令，并且把这一周的工作告诉 Claude Code 后，你能惊讶的发现，它居然真的在按照你的 Workflow 设定工作！正如下图一样：
Claude Code 会：
先问你本周做了什么
帮你整理、分类、提炼
按照模板生成一份漂亮的周报
从此，周五下班前的周报焦虑，不复存在！ 🎉
第四章：三个让 Skill 更强大的进阶技巧
Skill 能做到的设置， 远远不止周报生成器这么简单，它甚至能够内嵌 Program 来应付各种需求，但限于篇幅有限，今天我们还是以周报生成器作为例子，以便大家理解！
技巧一：用配置文件实现"一键切换"
如果你需要在不同场景下使用同一个 Skill（比如给不同部门写周报，格式要求不同），可以用配置文件来实现。
里面的 Json 格式文件，可以设置好结构化数据，如下：
最后，必须要在 Skill.md 里面引用文件，否则不会生效！
这样，切换部门只需要改一下配置文件的引用，不用改任何指令。
技巧二：用“禁止清单”防止 Claude Code犯错
有时候，告诉 Claude "不要做什么" 比告诉它 "要做什么" 更有效
我们可以在 Rule/ 目录下创建一个 dont-do.md ：
然后同样的，必须在 SKILL.md 中强调：
技巧三：用“检查清单”确保质量
在最后一步加一个自检环节，让 Claude 在输出前自己检查一遍。
可以在 Workflow 中，多加一个自检的步骤：
这就像给 Claude 配了一个"质检员"，大大减少低级错误。
结语：你不是在写 Skill，你是在构建一个“数字员工”
从最初那个臃肿、混乱的 SKILL.md，到现在我们面前这个结构清晰、权责分明的“企业级黄金架构”，我们走过了一段从“炼金术”到“现代化学”的旅程。我们不再满足于偶然调配出有效的“魔法药水”（Prompt），而是开始系统性地构建稳定、可预测、可扩展的“分子结构”（Skill 架构）。
这，就是 Claude Code Skills 2.0 的精髓所在。
当你开始用“架构”的眼光去审视你的 Skill，你赋予 Claude 的，就不再是一条条孤立的指令，而是一个完整的、结构化的“数字大脑”。
记住，你所做的，远不止是提升 AI 的工作效率。你是在定义一种全新的、与人工智能深度协作的未来。在这个未来里，我们不再是 AI 的“使用者”，而是它的“设计者”和“架构师”。我们构建的每一个结构精良的 Skill，都是在为这个智能时代，添上一块坚实的基石。
