structure｜1️⃣ 三级笔记、思想框架

《Claude Skills 的完整构建手册》三级笔记

核心观点

这份手册的主旨是：Claude Skills 不是一段提示词，而是一种把重复工作流、团队偏好、领域知识和工具使用方法打包成可复用能力的机制。一个 skill 本质上是一个简单文件夹，通过 SKILL.md、可选脚本、参考资料和资产，让 Claude 在合适场景下自动加载必要知识，并把一次性说明变成稳定执行路径。

文章同时面向两条路线：一条是独立 skill，用来稳定生成文档、设计、代码、研究流程等产物；另一条是 MCP 增强 skill，用来把已有 MCP 的原始工具访问封装成可理解、可执行、可复用的工作流。共同目标是降低用户重复提示成本，提高执行一致性。

一、Skill 的基本定义：把工作流封装成文件夹

1.1 Skill 是什么

• Skill 是一组说明，被打包成简单文件夹，用来教 Claude 处理特定任务或流程。
• 它适合重复性工作：前端设计生成、固定方法论研究、团队风格文档、多步骤流程编排。
• 它不是替代 Claude 的通用能力，而是把用户的偏好、流程和领域经验提前沉淀，让 Claude 每次遇到同类任务时不必从零理解。

1.2 一个 skill 文件夹包含什么

• SKILL.md 是必需文件，包含 Markdown 指令和 YAML frontmatter。
• scripts/ 是可选目录，用于放 Python、Bash 等可执行代码。
• references/ 是可选目录，用于放按需加载的文档。
• assets/ 是可选目录，用于放模板、字体、图标等产出资源。

1.3 适用对象

• 开发者：希望 Claude 稳定遵循特定工程流程。
• 高级用户：希望把自己的工作方法变成可复用能力。
• 团队：希望组织内多个成员用 Claude 时保持一致标准。

二、Fundamentals：技能设计的三条底层原则

2.1 Progressive Disclosure：分层加载，减少上下文浪费

• 第一层是 YAML frontmatter，始终进入系统提示，只提供触发判断所需的最小信息。
• 第二层是 SKILL.md 正文，在 Claude 判断 skill 相关时加载，包含完整指导。
• 第三层是链接文件，比如 references/、scripts/、assets/，只有任务需要时才继续读取。
• 这个设计让 skill 既能提供专业知识，又不把所有资料一次性塞进上下文。

2.2 Composability：多个 skill 可以同时工作

• Claude 可以同时加载多个 skills，因此每个 skill 都应该能与其他能力组合。
• 好的 skill 不假设自己是唯一能力，而是清楚声明自己的边界、输入、输出和触发条件。

2.3 Portability：一次创建，多端可用

• 同一个 skill 可以在 Claude.ai、Claude Code 和 API 中工作。
• 可移植的前提是依赖环境可用；如果 skill 需要系统包、脚本运行时或外部服务，需要在说明里写清。

三、Skills + MCP：MCP 提供连接，skill 提供做法

3.1 厨房类比

• MCP 像专业厨房，提供工具、食材和设备，即服务连接、实时数据访问和工具调用。
• Skill 像菜谱，告诉 Claude 怎样用这些工具完成有价值的事情。
• 二者结合后，用户不需要每次都解释工具调用顺序、异常处理和最佳实践。

3.2 MCP 用户为什么需要 skill

• 没有 skill 时，用户可能已经连接 MCP，却不知道下一步该做什么。
• 每次对话都从零开始，用户提示差异会导致结果不一致。
• 有 skill 时，预置工作流可以自动触发，工具使用方式更稳定，支持成本也更低。

四、Planning and Design：先定义用例，再写代码

4.1 从 2-3 个具体用例开始

• 写 skill 前先明确用户到底想完成什么。
• 一个好的用例要写清触发语、步骤、需要哪些工具、结果是什么。
• 例如 sprint planning 用例应包括获取项目状态、分析团队速度与容量、建议优先级、创建任务等步骤。

4.2 三类常见 use case

• 第一类是 Document & Asset Creation：创建稳定、高质量输出，如文档、演示、应用、设计、代码。
• 第二类是 Workflow Automation：把多步骤流程写成可重复执行的方法，尤其适合跨多个工具的协作。
• 第三类是 MCP Enhancement：把 MCP 原始工具能力上升为面向用户目标的工作流指导。

4.3 定义成功标准

• 定量指标包括：相关查询触发率、完成工作流所需工具调用数、API 失败率。
• 定性指标包括：用户是否还需要反复提示下一步、工作流是否能不经修正完成、不同会话中结果是否一致。
• 这些指标是粗略 benchmark，不是绝对阈值；重点是让迭代有可观察依据。

五、Technical requirements：文件结构和 frontmatter 是基础设施

5.1 文件命名规则

• SKILL.md 必须大小写完全一致。
• skill 文件夹名应使用 kebab-case，避免空格、下划线和大写。
• skill 文件夹内部不要放 README.md；面向 Claude 的文档应放在 SKILL.md 或 references/。

5.2 YAML frontmatter 是触发入口

• 最小 frontmatter 包含 name 和 description。
• name 应与文件夹名匹配，使用 kebab-case。
• description 必须同时说明这个 skill 做什么、什么时候用，并包含具体触发场景。
• frontmatter 不能包含 XML angle brackets，也不能使用保留名称。

5.3 主说明要具体、可执行、可排错

• 指令应明确到可以执行，例如运行什么脚本、输入是什么、成功输出是什么。
• 常见错误要写清原因和修复方法。
• 如果细节太多，应放入 references/，让 SKILL.md 保持主流程清晰。

六、Testing and iteration：先跑通一个难任务，再扩展覆盖面

6.1 三种测试层次

• Manual testing：直接在 Claude.ai 中测试，适合快速迭代。
• Scripted testing：在 Claude Code 中用脚本自动跑测试，适合可重复验证。
• Programmatic testing：通过 skills API 构建系统化评估，适合更正式的生产流程。

6.2 先围绕单个任务迭代

• 作者建议先挑一个有挑战的任务，把它跑到稳定成功。
• 当上下文内的成功做法出现后，再把这套做法抽取成 skill。
• 这比一开始铺开大量 test cases 更快得到有效信号。

6.3 测试三件事

• Triggering tests：相关请求应该触发，不相关请求不应触发。
• Functional tests：API 调用成功、输出正确、异常处理有效、边界情况覆盖。
• Performance comparison：比较有 skill 和无 skill 时的消息轮次、失败调用、token 消耗和完成质量。

七、Distribution and sharing：skill 既要能安装，也要能被理解

7.1 分发路径

• 个人用户可以下载 skill 文件夹、按需压缩，并上传到 Claude.ai，或放到 Claude Code 的 skills 目录。
• 组织级 skill 可以由管理员部署到整个 workspace，支持集中管理和自动更新。
• Agent Skills 被描述为开放标准，目标是让 skill 像 MCP 一样跨工具、跨平台可移植。

7.2 API 使用场景

• 终端用户交互适合 Claude.ai / Claude Code。
• 应用、自动化管线、生产部署和 agent 系统更适合通过 API 管理和执行 skills。
• API 路线需要理解 skills endpoint、container skills 参数和相关执行环境要求。

7.3 对外文档要讲 outcome，而不是只讲文件结构

• 推荐把 skill 放在 GitHub，提供清楚的 README、安装说明和示例截图。
• 如果 skill 配合 MCP server 使用，MCP 文档应解释两者一起使用的价值。
• 定位时要强调用户能更快完成什么，而不是只说它包含哪些文件。

八、Patterns and troubleshooting：把常见工作方式写成稳定模式

8.1 两种入口：problem-first 和 tool-first

• Problem-first 是用户先描述问题，skill 负责选择工具和编排步骤。
• Tool-first 是用户已经知道某个工具或 MCP，skill 负责告诉 Claude 如何正确使用。
• 选哪种取决于用户真实心智模型：他们是带着目标来，还是带着工具来。

8.2 五类模式

• Sequential workflow orchestration：适合严格按顺序执行的多步骤流程。
• Multi-MCP coordination：适合跨 Figma、Drive、Linear、Slack 等多个服务传递数据。

concepts｜2️⃣ 关键概念、概念网络

agentic reading｜3️⃣ 费曼 x3