单文件 SKILL.md 的两大困境
困境一：上下文的隐性负担
把所有指令、规则、示例代码、参考文档全部堆在一个 SKILL.md 里，每次触发 Skill 都是一次沉重的上下文加载。Claude 就像一个时刻背着百科全书的学者，查一句话也得扛着整本书。
直接后果：
- 性能下降：庞大的 SKILL.md 消耗更多处理时间，交互变得迟钝
- 关键信息丢失：上下文接近极限时，模型会"遗忘"开头或中间的关键指令，产生"指令漂移"
- 预算超支：更大的上下文意味着更高的 Token 消耗
困境二：维护的噩梦
一个超过 500 行的 SKILL.md 就是维护灾难。更新某个知识点时，你不得不在巨大的文本中小心翼翼地定位和修改，同时祈祷不会影响到其他部分。
- 逻辑混乱：写到后面，自己都看不懂自己在做什么
- 可读性差：协作者接手时成本极高
- 修改风险高：原本能跑的，改完可能就废了
核心思想：模块化与渐进式披露
Skills 2.0 的核心理念类似于阅读一本书的方式：
- 先看目录（SKILL.md）：对全局结构有宏观了解
- 按需阅读章节（引用文件）：只在需要时才深入具体内容
Claude Code 使用 Skill 的方式完全相同——先加载轻量的"目录"（SKILL.md），然后根据任务需要，通过文件链接去"翻阅"拆分出去的各种 .md、.py 或 .json 文件。
精髓在于：将庞大的知识体系拆解成独立、内聚、可管理的"知识积木"，通过 SKILL.md 这个"蓝图"有机组织起来。
关键规则：如果 SKILL.md 里没有提及某个文件，该文件永远不会被 Claude 使用。
两种经典架构模式
模式一：知识库型架构（Knowledge Base）
适用场景：为 Claude 提供一套静态的、结构化的知识，例如：
- 公司内部 API 文档
- 编程框架（React、Vue 等）的最佳实践
- 团队共享的设计规范或写作风格指南
核心理念：将知识"原子化"。每个独立知识点对应一个独立文件，SKILL.md 扮演"索引"角色。
工作原理示例：当用户问"公司的 OKR 是什么意思"时，Claude 会先看 SKILL.md，发现这是术语问题，打开 knowledge/术语表.md 找到解释并回答——不会去打开"产品FAQ"或"报销流程"等无关文件。这就是"按需取用"的威力。
模式二：工作流型架构（Workflow）
适用场景：完成多步骤任务，例如：
- 写周报（收集信息 → 整理 → 按格式输出）
- 做会议纪要（听录音 → 提取要点 → 生成文档）
- 发布文章（检查格式 → 配图 → 发布到平台）
核心理念：将任务"流程化"。把复杂任务拆解为线性的、可独立执行和验证的步骤，每个步骤对应一个独立文件。
工作原理示例：当用户说"帮我写周报"时，Claude 会看 SKILL.md 了解整体流程，依次执行 step1 → step2 → step3，在对应步骤中打开模板文件来格式化输出。每完成一步自动推进到下一步。
如何选择？
| 维度 | 知识库型 | 工作流型 |
|---|---|---|
| 核心目的 | 提供参考知识 | 执行多步骤任务 |
| 文件组织 | 按主题分类 | 按步骤排序 |
| 典型用途 | FAQ、规范、文档 | 自动化流程、生成任务 |
两种模式并非互斥——你完全可以在工作流型 Skill 中引入 reference/ 目录存放知识库型参考文档。
实战：10 分钟打造"AI 周报助手"
第一步：创建文件夹结构
mkdir -p ~/.claude/skills/weekly-report/{workflow,rules,templates}
完成后的目录结构：
weekly-report/
├── SKILL.md # 主控文件
├── rules/
│ └── writing-rules.md # 写作规范
├── templates/
│ └── report-template.md # 周报模板
└── workflow/
├── step1-collect.md # 搜集信息
├── step2-organize.md # 整理内容
└── step3-generate.md # 生成周报
第二步：编写写作规范（rules/writing-rules.md）
定义周报的写作风格、语气、格式要求等。告诉 Claude 应该用什么语言风格输出，哪些内容必须包含，哪些要避免。
第三步：编写周报模板（templates/report-template.md）
定义周报的输出格式，Claude 会严格按照模板生成内容。包含本周完成事项、下周计划、需要协助的问题等板块。
第四步：编写工作流步骤
- step1-collect.md：定义信息搜集策略，引导 Claude 向用户提问本周工作内容
- step2-organize.md：定义内容整理逻辑，按优先级和类别分类
- step3-generate.md：定义生成规则，引用模板文件，输出最终周报
第五步：编写主控文件（SKILL.md）
这是整个 Skill 的"大脑"，负责串联所有模块。核心结构：
- 声明 Skill 触发条件
- 列出所有引用文件的路径和用途
- 定义工作流执行顺序
- 指明规则文件的约束范围
第六步：验证运行
将 Skill 放在 ~/.claude/skills/ 目录下后，在 Claude Code 中触发对应指令，观察 Claude 是否按照工作流步骤依次执行。
三个进阶技巧
技巧一：配置文件实现场景切换
为不同场景（如不同部门的周报格式）创建 JSON 配置文件：
configs/
├── tech-team.json
└── marketing-team.json
在 SKILL.md 中引用对应配置文件，切换场景只需改一行引用路径，无需修改任何指令逻辑。
技巧二：用"禁止清单"防止犯错
在 rules/ 目录下创建 dont-do.md，明确告诉 Claude "不要做什么"——有时候这比告诉它"要做什么"更有效。例如：不要编造数据、不要使用非正式用语、不要输出超过指定长度等。
必须在 SKILL.md 中显式引用该文件，否则不会生效。
技巧三：用"检查清单"确保输出质量
在工作流末尾增加一个自检步骤，让 Claude 在最终输出前对照检查清单自查一遍。相当于给 Claude 配了一个"质检员"，能显著减少格式错误、内容遗漏等低级问题。
延伸思考
Skills 文档架构的本质是将提示工程从"写一段提示词"升级为"设计一个系统"。当你用架构思维去组织 Skill，赋予 Claude 的不再是孤立的指令，而是一个完整的、结构化的工作体系。对于一人公司的独立开发者来说，一套设计精良的 Skills 架构，就是你最稳定的"数字员工"——可复用、可迭代、可扩展。