企业官网建设流程全解析

• AI 插件
• 开发工具
• 插件系统

本指南以 claude-plugins-official 仓库内 plugin-dev 插件的 skill-development 技能文档为核心，系统讲解如何为 Claude Code 插件创建高质量的 Skill：从 SKILL.md 的目录结构与 YAML frontmatter 规范，到三级渐进式披露的上下文管理原理，再到从需求理解、资源规划、编写、验证到迭代的完整六步流程。读完本文，你将掌握编写"触发器描述精准、正文精炼、资源分层"的插件 Skill 的全部实操方法与可复用的检查清单。

什么是 Skill：把通用 Agent 变成领域专家

Skill 是模块化、自包含的能力包，通过提供专门的知识、工作流和工具来扩展 Claude 的能力。可以把 Skill 理解为特定领域或任务的"上岗引导手册"（onboarding guide）——它把 Claude 从一个通用型 Agent 转变为一个配备程序性知识的专用 Agent，而这些程序性知识是任何预训练模型都无法完整内化的。

一个 Skill 通常提供四类内容（见 skill-development/SKILL.md）：

1. 专用工作流：面向特定领域的多步骤流程；
2. 工具集成：与特定文件格式或 API 协作的指令；
3. 领域专业知识：公司特有的知识、模式、业务逻辑；
4. 捆绑资源：为复杂与重复性任务准备的脚本、参考资料和素材。

Skill 的解剖结构：SKILL.md 与三类捆绑资源

每个 Skill 由必需的SKILL.md文件加上可选的捆绑资源组成，标准目录结构如下：

skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter metadata (required) │ │ ├── name: (required) │ │ └── description: (required) │ └── Markdown instructions (required) └── Bundled Resources (optional) ├── scripts/ - Executable code (Python/Bash/etc.) ├── references/ - Documentation intended to be loaded into context as needed └── assets/ - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必需）

YAML frontmatter 中的name和description决定了 Claude 何时会使用这个 Skill。描述必须具体说明该 Skill 做什么、何时使用，并且使用第三人称书写（例如 "This skill should be used when..."，而不是 "Use this skill when..."）。这一点在 plugin-dev 的 README 中被明确列为所有技能统一遵循的文档标准之一。

scripts/（可选）

用于需要确定性可靠性或会被反复重写的任务的可执行代码（Python/Bash 等）。

• 何时包含：同一段代码被反复重写，或需要确定性的执行结果时；
• 示例：PDF 旋转任务对应的scripts/rotate_pdf.py；
• 优势：Token 高效、确定性执行，且可以不加载进上下文直接运行；
• 注意：脚本仍可能被 Claude 读取以便进行修补或适配特定环境。

references/（可选）

按需加载进上下文、用于指导 Claude 过程与思考的文档和参考资料。

• 何时包含：需要 Claude 在工作时参考的文档；
• 典型例子：财务模式references/finance.md、公司 NDA 模板references/mnda.md、公司政策references/policies.md、API 规格references/api_docs.md；
• 适用场景：数据库模式、API 文档、领域知识、公司政策、详细工作流指南；
• 优势：保持 SKILL.md 精简，仅在 Claude 判断需要时才加载；
• 最佳实践：若文件很大（超过 10k 词），应在 SKILL.md 中提供 grep 搜索模式；
• 避免重复：信息要么放在 SKILL.md 中，要么放在 references 文件中，不要两处都放。除非内容对 Skill 真正核心，否则优先放到 references 文件——这样既让 SKILL.md 保持精简，又避免占用上下文窗口。SKILL.md 中只保留必要的程序性指令与工作流指引，详细的参考资料、模式与示例一律移入 references 文件。

assets/（可选）

不打算加载进上下文、而是用于 Claude 产出物中的文件。

• 何时包含：Skill 需要会在最终输出中被使用的文件时；
• 示例：品牌素材assets/logo.png、PPT 模板assets/slides.pptx、HTML/React 样板代码assets/frontend-template/、字体assets/font.ttf；
• 适用场景：模板、图片、图标、样板代码、字体、会被复制或修改的示例文档；
• 优势：把输出型资源与文档分离，Claude 无需加载即可使用这些文件。

渐进式披露：三级上下文加载机制

Skill 采用三级加载系统来高效管理上下文窗口（这是 plugin-dev 所有技能共同遵循的核心设计原则，参见 plugin-dev/README.md 中 "Progressive Disclosure" 一节）：

1. 元数据（name + description）：始终在上下文中（约 100 词）；
2. SKILL.md 正文：当 Skill 被触发时加载（少于 5k 词）；
3. 捆绑资源：按 Claude 需要加载（无上限*）。

* 之所以"无上限"，是因为脚本可以不读入上下文窗口而直接执行。

这套机制的价值在于：元数据常驻上下文、成本极低，保证了 Skill 的"可发现性"；正文按需加载、保持精简，避免污染上下文；深度知识放在引用文件中，需要时才进入窗口。plugin-dev 自带的 skill-reviewer Agent 在其审查流程中专门检查渐进式披露是否有效（检查 SKILL.md / references/ / examples/ / scripts/ 的划分与相互引用是否到位），详见 skill-reviewer.md。

Skill 创建流程：六步走

创建 Skill 时应按顺序执行以下流程，只有在有明确理由时才跳过某一步。

第 1 步：用具体示例理解 Skill 的使用场景

只有当 Skill 的使用模式已经非常清晰时才可以跳过此步；即使是改造已有 Skill，这一步仍然有价值。要创建有效的 Skill，必须清楚理解 Skill 将被如何使用——理解可以来自用户直接给出的示例，也可以来自经过用户反馈验证的生成示例。

以构建 image-editor Skill 为例，需要澄清的问题包括：

• "这个 image-editor Skill 应支持哪些功能？编辑、旋转，还有其他吗？"
• "能举几个这个 Skill 的使用例子吗？"
• "我能想象用户会提出类似『去掉这张图片的红眼』或『旋转这张图片』的请求。你还设想它会被以哪些方式使用？"
• "用户说什么样的话应该触发这个 Skill？"

为避免让用户不堪重负，不要在一条消息里问太多问题。从最重要的问题开始，后续再追问补充。当对 Skill 应支持的功能有了清晰认知时，此步结束。

第 2 步：规划可复用的 Skill 内容

要把具体示例转化为有效 Skill，需要对每个示例做两件事：

1. 思考如何从零开始执行该示例；
2. 识别在反复执行这些工作流时，哪些脚本、引用文件和素材会有帮助。

文档给出了三组经典分析案例：

• pdf-editor：针对"帮我把这个 PDF 旋转一下"这类请求，分析发现——旋转 PDF 每次都要重写同样的代码，于是把scripts/rotate_pdf.py脚本存进 Skill 更合适；
• frontend-webapp-builder：针对"帮我建一个 todo 应用"或"做一个追踪步数的仪表盘"这类请求，分析发现——每次写前端都要同样的 HTML/React 样板，于是assets/hello-world/模板更合适；
• big-query：针对"今天有多少用户登录了？"这类请求，分析发现——每次查询都要重新发现表结构与关系，于是references/schema.md记录表模式的文档更合适。

对于 Claude Code 插件场景，文档还专门给出了 hooks Skill 的分析：开发者反复需要校验 hooks.json、测试 hook 脚本，因此scripts/validate-hook-schema.sh与scripts/test-hook.sh这类工具脚本很有帮助，而详细的 hook 模式应放在references/patterns.md以避免撑大 SKILL.md。

本仓库中 hook-development 的资源配置正是这一分析思路的落地：3 个参考文件（patterns、migration、advanced）+ 3 个示例脚本 + 3 个工具脚本。

第 3 步：创建 Skill 目录结构

对于 Claude Code 插件，直接在插件skills/目录下创建 Skill 结构：

mkdir -p plugin-name/skills/skill-name/{references,examples,scripts} touch plugin-name/skills/skill-name/SKILL.md

注意：与通用 skill-creator 使用init_skill.py脚本不同（后者会生成带 TODO 占位符的模板并创建scripts/、references/、assets/示例目录，参见 skill-creator-original.md），插件 Skill 采用更简单的手工结构，直接在插件的skills/目录中创建。

第 4 步：编辑 Skill

编辑（新建或已有）Skill 时，始终记住：这个 Skill 是给另一个 Claude 实例使用的。应聚焦于那些对 Claude 有益且不显然的信息——什么样的程序性知识、领域细节或可复用资源，能帮助另一个 Claude 实例更有效地执行这些任务。

从可复用内容开始：先实现上面识别出的scripts/、references/、assets/文件。注意此步可能需要用户输入——例如实现 brand-guidelines Skill 时，用户可能需要提供品牌素材或模板存入assets/，或提供文档存入references/。同时，删除任何不需要的示例文件和目录，只创建实际需要的目录。

更新 SKILL.md 时遵循写作风格要求：整个 Skill 使用祈使句/不定式形式（动词开头的指令），而不是第二人称。例如 "To accomplish X, do Y"，而不是 "You should do X"。

frontmatter 中的 description 使用第三人称 + 具体触发短语：

--- name: Skill Name description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", "specific phrase 3". Include exact phrases users would say that should trigger this skill. Be concrete and specific. version: 0.1.0 ---

好的描述示例：

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", "implement prompt-based hooks", or mentions hook events (PreToolUse, PostToolUse, Stop).

坏的描述示例：

description: Use this skill when working with hooks. # 人称错误、含糊 description: Load when user needs hook help. # 非第三人称 description: Provides hook guidance. # 没有触发短语

完成 SKILL.md 正文时回答三个问题：1) 该 Skill 的目的是什么（几句话）；2) 何时应使用该 Skill（写进 frontmatter description 并带具体触发器）；3) 实践中 Claude 应如何使用该 Skill——上面开发的所有可复用内容都要被引用到，让 Claude 知道如何用它们。

保持 SKILL.md 精简：正文目标 1,500–2,000 词。详细内容移入 references/：

• 详细模式 →references/patterns.md
• 高级技巧 →references/advanced.md
• 迁移指南 →references/migration.md
• API 参考 →references/api-reference.md

在 SKILL.md 中引用资源：

## Additional Resources ### Reference Files For detailed patterns and techniques, consult: - **`references/patterns.md`** - Common patterns - **`references/advanced.md`** - Advanced use cases ### Example Files Working examples in `examples/`: - **`example-script.sh`** - Working example

第 5 步：验证与测试

插件 Skill 的验证与通用 Skill 不同，检查项如下：

1. 检查结构：Skill 目录位于plugin-name/skills/skill-name/；
2. 验证 SKILL.md：包含带 name 和 description 的 frontmatter；
3. 检查触发短语：description 包含具体的用户查询措辞；
4. 验证写作风格：正文使用祈使句/不定式形式，而非第二人称；
5. 测试渐进式披露：SKILL.md 精简（约 1,500–2,000 词），详细内容放在 references/ 中；
6. 检查引用：所有被引用的文件真实存在；
7. 验证示例：示例完整且正确；
8. 测试脚本：脚本可执行且工作正常。

使用 skill-reviewer Agent：

Ask: "Review my skill and check if it follows best practices"

该 Agent 会检查描述质量、内容组织和渐进式披露。它在 skill-reviewer.md 中定义了完整的审查输出格式，包括描述分析（当前描述、问题、建议改写）、内容质量评估（词数、写作风格、组织）、渐进式披露评估（各目录文件数与词数）、按严重程度分级的具体问题清单，以及通过/需改进/需大改的总体评级。

第 6 步：迭代

测试 Skill 后，用户可能提出改进要求——这通常发生在刚使用过 Skill 之后，此时对 Skill 的实际表现有最新鲜的上下文。

迭代工作流：

1. 在真实任务上使用该 Skill；
2. 留意痛点或低效之处；
3. 判断 SKILL.md 或捆绑资源应如何更新；
4. 实施修改并再次测试。

常见改进方向：

• 加强 description 中的触发短语；
• 把 SKILL.md 中的长段落移入 references/；
• 补充缺失的示例或脚本；
• 澄清含糊的指令；
• 增加边界情况处理。

插件内 Skill 的特殊之处

Skill 在插件中的位置

插件 Skill 位于插件的skills/目录：

my-plugin/ ├── .claude-plugin/ │ └── plugin.json ├── commands/ ├── agents/ └── skills/ └── my-skill/ ├── SKILL.md ├── references/ ├── examples/ └── scripts/

这与 plugin-structure 中描述的插件组件组织规范一致：skills/是插件根级组件目录，每个 Skill 一个子目录、内含必需的SKILL.md。

自动发现

Claude Code 会自动发现 Skill：

• 扫描skills/目录；
• 查找包含SKILL.md的子目录；
• 始终加载 Skill 元数据（name + description）；
• Skill 触发时加载 SKILL.md 正文；
• 需要时加载 references/examples。

无需打包

插件 Skill 作为插件的一部分随插件分发，而不是独立的 ZIP 文件。用户安装插件时就获得了其中的 Skill。（这与通用 skill-creator 的package_skill.py打包为 zip 的流程形成对比，详见 skill-creator-original.md。）

在插件中测试

通过本地安装插件来测试 Skill：

# Test with --plugin-dir cc --plugin-dir /path/to/plugin # Ask questions that should trigger the skill # Verify skill loads correctly

研读 plugin-dev 内部的 Skill 范例

plugin-dev 插件自身的技能就是最佳实践样本（目录见 plugins/plugin-dev/skills）：

• hook-development：触发短语出色（"create a hook"、"add a PreToolUse hook" 等）；SKILL.md 精简（1,651 词）；3 个 references/ 文件承载详细内容；3 个可工作的 hook 示例；3 个工具脚本；
• agent-development：触发词有力（"create an agent"、"agent frontmatter" 等）；SKILL.md 聚焦（1,438 词）；references 中包含来自 Claude Code 的 AI 生成提示；完整的 Agent 示例；
• plugin-settings：触发器具体（"plugin settings"、".local.md files"、"YAML frontmatter"）；references 展示真实实现（multi-agent-swarm、ralph-loop）；可工作的解析脚本。

每个范例都体现了渐进式披露与强触发器设计。plugin-dev 的 README 还给出了全部 7 个技能（hook、mcp、structure、settings、command、agent、skill development）的资源构成统计，可作为对标基准。

内容分层：SKILL.md / references/ / examples/ / scripts/ 各放什么

放入 SKILL.md（Skill 触发时总是加载）

• 核心概念与概述；
• 必要流程与工作流；
• 快速参考表；
• 指向 references/examples/scripts 的指针；
• 最常见的使用场景。

控制在 3,000 词以内，理想为 1,500–2,000 词。

移入 references/（按需加载）

• 详细模式与高级技巧；
• 完整的 API 文档；
• 迁移指南；
• 边界情况与故障排查；
• 大量示例与走查。

每个引用文件可以很大（2,000–5,000+ 词）。

放入 examples/

可工作的代码示例：

• 完整、可运行的脚本；
• 配置文件；
• 模板文件；
• 真实世界的使用示例。

用户可直接复制并改编这些示例。

放入 scripts/

工具脚本：

• 校验工具；
• 测试辅助；
• 解析工具；
• 自动化脚本。

脚本应可执行且有文档说明。

写作风格要求

祈使句/不定式形式

使用动词开头的指令，而非第二人称：

正确（祈使句）：

To create a hook, define the event type. Configure the MCP server with authentication. Validate settings before use.

错误（第二人称）：

You should create a hook by defining the event type. You need to configure the MCP server. You must validate settings before use.

description 中的第三人称

frontmatter 的 description 必须使用第三人称：

正确：

description: This skill should be used when the user asks to "create X", "configure Y"...

错误：

description: Use this skill when you want to create X... description: Load this skill when user asks...

客观、指令式语言

关注"做什么"，而不是"谁来做"：

正确：

Parse the frontmatter using sed. Extract fields with grep. Validate values before use.

错误：

You can parse the frontmatter... Claude should extract fields... The user might validate values...

定稿前的验证清单

在最终确定一个 Skill 前，逐项检查（这与 skill-reviewer.md 中 Agent 的审查维度一一对应）：

结构：

• SKILL.md 存在且包含有效的 YAML frontmatter
• frontmatter 包含name和description字段
• Markdown 正文存在且内容充实
• 被引用的文件真实存在

描述质量：

• 使用第三人称（"This skill should be used when..."）
• 包含用户会说的具体触发短语
• 列出具体场景（"create X"、"configure Y"）
• 不模糊、不通用

内容质量：

• SKILL.md 正文使用祈使句/不定式形式
• 正文聚焦且精简（理想 1,500–2,000 词，最多 5k）
• 详细内容已移入 references/
• 示例完整且可工作
• 脚本可执行且有文档

渐进式披露：

• 核心概念在 SKILL.md
• 详细文档在 references/
• 可工作代码在 examples/
• 工具在 scripts/
• SKILL.md 引用了这些资源

测试：

• Skill 能在预期的用户查询下触发
• 内容对目标任务有帮助
• 文件之间无重复信息
• references 按需加载

四大常见错误与规避

错误 1：触发描述太弱

❌坏：

description: Provides guidance for working with hooks.

坏的原因：含糊、没有具体触发短语、不是第三人称。

✅好：

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events. Provides comprehensive hooks API guidance.

好的原因：第三人称、具体短语、具体场景。

错误 2：SKILL.md 塞了太多内容

❌坏：

skill-name/ └── SKILL.md (8,000 words - everything in one file)

坏的原因：Skill 加载时撑大上下文，详细内容总是被加载。

✅好：

skill-name/ ├── SKILL.md (1,800 words - core essentials) └── references/ ├── patterns.md (2,500 words) └── advanced.md (3,700 words)

好的原因：渐进式披露，详细内容仅在需要时加载。

错误 3：第二人称写作

❌坏：

You should start by reading the configuration file. You need to validate the input. You can use the grep tool to search.

✅好：

Start by reading the configuration file. Validate the input before processing. Use the grep tool to search for patterns.

错误 4：缺少资源引用

❌坏：

# SKILL.md [Core content] [No mention of references/ or examples/]

坏的原因：Claude 根本不知道 references 存在。

✅好：

# SKILL.md [Core content] ## Additional Resources ### Reference Files - **`references/patterns.md`** - Detailed patterns - **`references/advanced.md`** - Advanced techniques ### Examples - **`examples/script.sh`** - Working example

好的原因：Claude 知道去哪里找补充信息。

Skill 规模速查：最小 / 标准 / 完整

最小 Skill

skill-name/ └── SKILL.md

适合：简单知识，不需要复杂资源。

标准 Skill（推荐）

skill-name/ ├── SKILL.md ├── references/ │ └── detailed-guide.md └── examples/ └── working-example.sh

适合：大多数需要详细文档的插件 Skill。

完整 Skill

skill-name/ ├── SKILL.md ├── references/ │ ├── patterns.md │ └── advanced.md ├── examples/ │ ├── example1.sh │ └── example2.json └── scripts/ └── validate.sh

适合：需要校验工具的复杂领域。

最佳实践总结

✅应该做：

• description 使用第三人称（"This skill should be used when..."）
• 包含具体触发短语（"create X"、"configure Y"）
• 保持 SKILL.md 精简（1,500–2,000 词）
• 使用渐进式披露（细节移入 references/）
• 使用祈使句/不定式形式写作
• 清晰引用辅助文件
• 提供可工作的示例
• 为常见操作创建工具脚本
• 研读 plugin-dev 的技能作为模板

❌不要做：

• 任何地方使用第二人称
• 触发条件含糊
• 把一切都塞进 SKILL.md（超过 3,000 词且没有 references/）
• 用第二人称写作（"You should..."）
• 资源不被引用
• 包含损坏或不完整的示例
• 跳过验证

完整实施工作流

为你的插件创建一个 Skill 的最终流程：

1. 理解用例：识别 Skill 使用的具体示例；
2. 规划资源：确定需要哪些 scripts/references/examples；
3. 创建结构：mkdir -p skills/skill-name/{references,examples,scripts}；
4. 编写 SKILL.md：
   • frontmatter 使用第三人称描述与触发短语；
   • 精简正文（1,500–2,000 词）且用祈使句；
   • 引用辅助文件；
5. 添加资源：按需创建 references/、examples/、scripts/；
6. 验证：检查描述、写作风格与组织；
7. 测试：确认 Skill 能在预期触发器下加载；
8. 迭代：根据使用情况持续改进。

核心要义浓缩为三点：强触发描述保证 Skill 在对的时刻被加载，渐进式披露保证加载时不浪费上下文，祈使句写作风格保证指令对 Claude 清晰可执行——三者齐备，你的 Skill 就能"该出现时出现、出现时精准、执行时高效"。

• AI 插件
• 开发工具
• 插件系统