AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载本指南以 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专用工作流面向特定领域的多步骤流程工具集成与特定文件格式或 API 协作的指令领域专业知识公司特有的知识、模式、业务逻辑捆绑资源为复杂与重复性任务准备的脚本、参考资料和素材。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 一节元数据name description始终在上下文中约 100 词SKILL.md 正文当 Skill 被触发时加载少于 5k 词捆绑资源按 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需要对每个示例做两件事思考如何从零开始执行该示例识别在反复执行这些工作流时哪些脚本、引用文件和素材会有帮助。文档给出了三组经典分析案例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.mdAPI 参考 →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 不同检查项如下检查结构Skill 目录位于plugin-name/skills/skill-name/验证 SKILL.md包含带 name 和 description 的 frontmatter检查触发短语description 包含具体的用户查询措辞验证写作风格正文使用祈使句/不定式形式而非第二人称测试渐进式披露SKILL.md 精简约 1,500–2,000 词详细内容放在 references/ 中检查引用所有被引用的文件真实存在验证示例示例完整且正确测试脚本脚本可执行且工作正常。使用 skill-reviewer AgentAsk: Review my skill and check if it follows best practices该 Agent 会检查描述质量、内容组织和渐进式披露。它在 skill-reviewer.md 中定义了完整的审查输出格式包括描述分析当前描述、问题、建议改写、内容质量评估词数、写作风格、组织、渐进式披露评估各目录文件数与词数、按严重程度分级的具体问题清单以及通过/需改进/需大改的总体评级。第 6 步迭代测试 Skill 后用户可能提出改进要求——这通常发生在刚使用过 Skill 之后此时对 Skill 的实际表现有最新鲜的上下文。迭代工作流在真实任务上使用该 Skill留意痛点或低效之处判断 SKILL.md 或捆绑资源应如何更新实施修改并再次测试。常见改进方向加强 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 descriptionSkill 触发时加载 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/skillshook-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 frontmatterreferences 展示真实实现multi-agent-swarm、ralph-loop可工作的解析脚本。每个范例都体现了渐进式披露与强触发器设计。plugin-dev 的 README 还给出了全部 7 个技能hook、mcp、structure、settings、command、agent、skill development的资源构成统计可作为对标基准。内容分层SKILL.md / references/ / examples/ / scripts/ 各放什么放入 SKILL.mdSkill 触发时总是加载核心概念与概述必要流程与工作流快速参考表指向 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 frontmatterfrontmatter 包含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.好的原因第三人称、具体短语、具体场景。错误 2SKILL.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 规模速查最小 / 标准 / 完整最小 Skillskill-name/ └── SKILL.md适合简单知识不需要复杂资源。标准 Skill推荐skill-name/ ├── SKILL.md ├── references/ │ └── detailed-guide.md └── examples/ └── working-example.sh适合大多数需要详细文档的插件 Skill。完整 Skillskill-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 的最终流程理解用例识别 Skill 使用的具体示例规划资源确定需要哪些 scripts/references/examples创建结构mkdir -p skills/skill-name/{references,examples,scripts}编写 SKILL.mdfrontmatter 使用第三人称描述与触发短语精简正文1,500–2,000 词且用祈使句引用辅助文件添加资源按需创建 references/、examples/、scripts/验证检查描述、写作风格与组织测试确认 Skill 能在预期触发器下加载迭代根据使用情况持续改进。核心要义浓缩为三点强触发描述保证 Skill 在对的时刻被加载渐进式披露保证加载时不浪费上下文祈使句写作风格保证指令对 Claude 清晰可执行——三者齐备你的 Skill 就能该出现时出现、出现时精准、执行时高效。赞分享AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载相关推荐Claude Code 插件 Skill 开发指南以 example-plugin 为模板理解 SKILL.md 结构、触发机制与渐进式披露Claude Code 插件 Skill 开发指南以 example plugin 为模板理解 SKILL.md 结构、触发机制与渐进式披露 本文以官方仓库AI 插件开发工具插件系统ForgeCode Skill 创作实战指南从 SKILL.md 结构到渐进式上下文披露的完整方法论ForgeCode Skill 创作实战指南从 SKILL.md 结构到渐进式上下文披露的完整方法论 本篇指南围绕 ForgeCode 仓库内置的 creat人工智能AI Agent代码智能体AI 应用CLI开发工具Gemini CLI 技能工厂skill-creator 内置技能全解——从 SKILL.md 结构、渐进式披露到打包安装的完整工程实践Gemini CLI 技能工厂skill creator 内置技能全解——从 SKILL.md 结构、渐进式披露到打包安装的完整工程实践 Gemini CLI人工智能AI Agent交互助手CLIMCP Clients上一篇portless macOS 钥匙串深挖security 命令、Touch ID 弹窗与重复证书清理指南下一篇Apache Kafka 系统级测试指南基于 ducktape 在 Docker、本地虚拟机与 EC2 上运行集成与性能测试创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Claude Code 插件 Skill 开发完全指南：SKILL.md 结构、渐进式披露与最佳实践
AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载本指南以 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专用工作流面向特定领域的多步骤流程工具集成与特定文件格式或 API 协作的指令领域专业知识公司特有的知识、模式、业务逻辑捆绑资源为复杂与重复性任务准备的脚本、参考资料和素材。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 一节元数据name description始终在上下文中约 100 词SKILL.md 正文当 Skill 被触发时加载少于 5k 词捆绑资源按 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需要对每个示例做两件事思考如何从零开始执行该示例识别在反复执行这些工作流时哪些脚本、引用文件和素材会有帮助。文档给出了三组经典分析案例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.mdAPI 参考 →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 不同检查项如下检查结构Skill 目录位于plugin-name/skills/skill-name/验证 SKILL.md包含带 name 和 description 的 frontmatter检查触发短语description 包含具体的用户查询措辞验证写作风格正文使用祈使句/不定式形式而非第二人称测试渐进式披露SKILL.md 精简约 1,500–2,000 词详细内容放在 references/ 中检查引用所有被引用的文件真实存在验证示例示例完整且正确测试脚本脚本可执行且工作正常。使用 skill-reviewer AgentAsk: Review my skill and check if it follows best practices该 Agent 会检查描述质量、内容组织和渐进式披露。它在 skill-reviewer.md 中定义了完整的审查输出格式包括描述分析当前描述、问题、建议改写、内容质量评估词数、写作风格、组织、渐进式披露评估各目录文件数与词数、按严重程度分级的具体问题清单以及通过/需改进/需大改的总体评级。第 6 步迭代测试 Skill 后用户可能提出改进要求——这通常发生在刚使用过 Skill 之后此时对 Skill 的实际表现有最新鲜的上下文。迭代工作流在真实任务上使用该 Skill留意痛点或低效之处判断 SKILL.md 或捆绑资源应如何更新实施修改并再次测试。常见改进方向加强 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 descriptionSkill 触发时加载 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/skillshook-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 frontmatterreferences 展示真实实现multi-agent-swarm、ralph-loop可工作的解析脚本。每个范例都体现了渐进式披露与强触发器设计。plugin-dev 的 README 还给出了全部 7 个技能hook、mcp、structure、settings、command、agent、skill development的资源构成统计可作为对标基准。内容分层SKILL.md / references/ / examples/ / scripts/ 各放什么放入 SKILL.mdSkill 触发时总是加载核心概念与概述必要流程与工作流快速参考表指向 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 frontmatterfrontmatter 包含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.好的原因第三人称、具体短语、具体场景。错误 2SKILL.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 规模速查最小 / 标准 / 完整最小 Skillskill-name/ └── SKILL.md适合简单知识不需要复杂资源。标准 Skill推荐skill-name/ ├── SKILL.md ├── references/ │ └── detailed-guide.md └── examples/ └── working-example.sh适合大多数需要详细文档的插件 Skill。完整 Skillskill-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 的最终流程理解用例识别 Skill 使用的具体示例规划资源确定需要哪些 scripts/references/examples创建结构mkdir -p skills/skill-name/{references,examples,scripts}编写 SKILL.mdfrontmatter 使用第三人称描述与触发短语精简正文1,500–2,000 词且用祈使句引用辅助文件添加资源按需创建 references/、examples/、scripts/验证检查描述、写作风格与组织测试确认 Skill 能在预期触发器下加载迭代根据使用情况持续改进。核心要义浓缩为三点强触发描述保证 Skill 在对的时刻被加载渐进式披露保证加载时不浪费上下文祈使句写作风格保证指令对 Claude 清晰可执行——三者齐备你的 Skill 就能该出现时出现、出现时精准、执行时高效。赞分享AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载相关推荐Claude Code 插件 Skill 开发指南以 example-plugin 为模板理解 SKILL.md 结构、触发机制与渐进式披露Claude Code 插件 Skill 开发指南以 example plugin 为模板理解 SKILL.md 结构、触发机制与渐进式披露 本文以官方仓库AI 插件开发工具插件系统ForgeCode Skill 创作实战指南从 SKILL.md 结构到渐进式上下文披露的完整方法论ForgeCode Skill 创作实战指南从 SKILL.md 结构到渐进式上下文披露的完整方法论 本篇指南围绕 ForgeCode 仓库内置的 creat人工智能AI Agent代码智能体AI 应用CLI开发工具Gemini CLI 技能工厂skill-creator 内置技能全解——从 SKILL.md 结构、渐进式披露到打包安装的完整工程实践Gemini CLI 技能工厂skill creator 内置技能全解——从 SKILL.md 结构、渐进式披露到打包安装的完整工程实践 Gemini CLI人工智能AI Agent交互助手CLIMCP Clients上一篇portless macOS 钥匙串深挖security 命令、Touch ID 弹窗与重复证书清理指南下一篇Apache Kafka 系统级测试指南基于 ducktape 在 Docker、本地虚拟机与 EC2 上运行集成与性能测试创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
