07-Skills定制完整指南

07 Skills定制完整指南 07 Skills定制完整指南 Modified May 9 Code block Bash Copy 1. 修改SKILL.md 添加或修改一些指令 2. 在Claude Code中发送新消息 不需要重启，修改会自动生效 3. 验证修改是否生效 检查AI是否应用了新的指令 如果未生效，尝试开始新对话或： /compact 技巧3：手动测试脚本 Code block Bash Copy 直接运行脚本看输出 cd .claude/skills/你的skill/scripts python 脚本名.py "测试输入" json 检查返回码 echo $? 0表示成功，非0表示失败 技巧4：检查文件编码 Code block Bash Copy 确保文件是UTF 8编码 file .claude/skills/你的skill/SKILL.md 应显示：UTF 8 Unicode text 技巧5：查看Skill加载日志 在Claude Code中输入： Code block Plain Text Copy 请列出当前已加载的所有Skills 这会显示所有被识别的Skills及其基本信息。 7.3 v2.1.129+ 新增：skillOverrides 设置 当你的项目或团队安装了大量 Skills 时，有些可能暂时不想用。从 v2.1.129 起，Claude Code 支持 skillOverrides 设置来控制每个 Skill 的可见性。 三种覆盖状态 配置位置 skillOverrides 写在 settings 文件中（项目级 .claude/settings.json 或用户级 /.claude/settings.json）： Code block JSON Copy { "skillOverrides": { "gongzhonghao writer": "user invocable only", "legacy helper": "off", "experimental tool": "name only" } } 适用场景： • 团队有几十个 Skills，但某个项目只想用其中几个 → 把其余设为 off • 某个 Skill 自动激活太频繁，但不舍得删 → 改为 user invocable only • 排查 Skill 冲突时，临时关闭部分 Skill 7.4 /skills 搜索过滤 当你安装了大量 Skills 时，直接输入 /skills 列表会很长。在较新版本中，/skills 支持搜索过滤： Code block Plain Text Copy /skills <关键词 例如 /skills comment 会过滤出名称或描述中包含 "comment" 的 Skill。这在管理十几个以上 Skill 时非常有用。 第八部分：FAQ（20个常见问题） Q1：Skill和Command有什么区别？ A：Command是"按钮"（触发器），Skill是"APP"（能力包）。Command用于显式触发，Skill用于封装知识和工具。两者通常配合使用：Command作为入口，Skill提供能力。 Q2：必须要SKILL.md吗？ A：是的，SKILL.md 是Skill的唯一必需文件。没有它Claude Code无法识别这是一个Skill。 Q3：SKILL.md可以是任意大小吗？ A：理论上可以，但建议控制在1000行以内。太大的SKILL.md会影响加载速度和AI理解。如果内容很多，考虑使用scripts/、config/等资源文件夹。 Q4：scripts支持哪些语言？ A：主要支持Python和Bash。推荐Python，因为生态好、跨平台、易维护。JavaScript也可以，但不如Python常用。 Q5：如何让Skill自动激活？ A：在SKILL.md的YAML Frontmatter中配置description字段。Claude Code会根据description判断何时激活。例如： Code block YAML Copy description: 当用户要求"添加注释"或"代码注释"时激活 Q6：可以有多个Skill吗？ A：可以。每个Skill是 .claude/skills/ 下的独立目录，可以有任意多个。 Q7：Skill之间会冲突吗？ A：如果description中描述的触发场景重复可能会冲突。建议每个Skill使用独特的触发场景描述。 Q8：如何更新Skill版本？ A：在SKILL.md的Markdown Body开头添加"版本历史"章节，记录每次变更。例如： Code block Markdown Copy 版本历史 V2.0.0 (2025 01 18) 适配当前版本新特性 改为SKILL.md单文件结构 V1.0.0 (2025 01 01) 初始版本 Q9：SKILL.md多大合适？ A：建议单个SKILL.md不超过1000行。太长会影响加载速度和AI理解。大的Skill应该考虑拆分成多个子Skill或使用scripts/。 Q10：如何调试Skill？ A： 1. 验证YAML Frontmatter格式 2. 手动运行scripts/中的脚本测试 3. 检查description是否清晰 4. 查看Claude Code的Skill加载日志 Q11：Hot Reloading不生效怎么办？ A： 1. 确认修改的是SKILL.md而不是其他文件 2. 检查YAML Frontmatter格式是否正确 3. 尝试使用/compact压缩上下文后重试 4. 最后手段：重启Claude Code Q12：如何处理中文路径问题？ A：Windows上尽量避免中文路径。如果必须使用，确保SKILL.md文件编码为UTF 8（带BOM或不带BOM都可以，但要一致）。 Q13：Skill可以调用MCP吗？ A：可以。在SKILL.md的Markdown Body中可以引用MCP工具。Claude Code会自动识别并调用。 Q14：如何共享Skill给团队？ A：将整个 .claude/skills/你的skill/ 目录提交到Git仓库。团队成员克隆后即可使用。 Q15：Skill可以跨项目使用吗？ A：可以。将Skill放在全局配置目录（ /.claude/skills/）即可在所有项目中使用。 Q16：如何回退到旧版本Skill？ A：使用Git回退到旧版本的提交，或者在SKILL.md的版本历史中查看旧版本的内容。 Q17：SKILL.md中可以使用变量吗？ A：SKILL.md 支持一个特殊内置变量 ${CLAUDE SKILL DIR}，其他自定义模板变量不支持。 ${CLAUDE SKILL DIR} 变量说明： • 含义：指向当前 Skill 文件（SKILL.md）所在的目录路径 • 用途：在 SKILL.md 正文中引用同目录下的其他文件（模板、配置、示例等） • 示例： Code block Markdown Copy 请阅读 ${CLAUDE SKILL DIR}/templates/code review.md 中的代码审查模板 请参考 ${CLAUDE SKILL DIR}/config/rules.yaml 中的规则配置 • 优势：使 Skill 可以组织为包含多个文件的目录结构，而不是将所有内容塞进一个 SKILL.md • 如果需要更复杂的动态内容，使用 scripts/ 中的脚本生成 Q18：如何测试Skill是否正常工作？ A： 1. 检查SKILL.md文件结构是否完整（YAML + Markdown） 2. 验证YAML Frontmatter格式 3. 手动测试scripts/中的脚本 4. 在Claude Code中测试触发词 Q19：Skill加载很慢怎么办？ A： 1. 减少SKILL.md的行数 2. 优化scripts/中的脚本性能 3. 检查是否有不必要的config/文件 Q20：如何学习更高级的Skill开发？ A： 1. 阅读公众号写作助手项目中的 SKILL.md 正文 2. 参考官方Skill示例 3. 实践中不断迭代优化 4. 理解渐进式披露和Hot Reloading机制 第九部分：附录 附录A：Skill目录快速创建脚本 macOS/Linux一键创建脚本： Code block Bash Copy !/bin/bash create skill.sh Skill目录结构一键创建 用法: ./create skill.sh <skill name SKILL NAME=$1 if [ z "$SKILL NAME" ]; then echo "用法: $0 <skill name " exit 1 fi SKILL DIR=".claude/skills/${SKILL NAME}" echo "创建Skill目录: ${SKILL NAME}" 创建目录结构 mkdir p "${SKILL DIR}/scripts" mkdir p "${SKILL DIR}/templates" mkdir p "${SKILL DIR}/config" 创建SKILL.md cat "${SKILL DIR}/SKILL.md" << EOF name: ${SKILL NAME} description: 请填写Skill的触发场景描述 ${SKILL NAME} 版本历史 V1.0.0 ($(date +%Y %m %d)) 初始版本 一、角色定义 [定义AI扮演的角色和背景] 二、核心能力 [列出3 5个核心能力] 三、工作流程 步骤1：[步骤名称] [详细说明和操作指南] 步骤2：[步骤名称] [详细说明和操作指南] 四、规则约束 [定义必须遵守的规则] 五、示例展示 [提供具体的好/坏示例] 六、输出格式 [定义输出的结构和格式] EOF 创建README cat "${SKILL DIR}/README.md" << EOF ${SKILL NAME} 版本 : 1.0.0 创建时间 : $(date +%Y %m %d) 功能说明 技巧3：手动测试脚本 技巧4：检查文件编码 技巧5：查看Skill加载日志 在Claude Code中输入： 这会显示所有被识别的Skills及其基本信息。 7.3 v2.1.129+ 新增：skillOverrides 设置 当你的项目或团队安装了大量 Skills 时，有些可能暂时不想用。从 v2.1.129 起，Claude Code 支持 skillOverrides 设置来控制每个 Skill 的可见性。 三种覆盖状态 配置位置 skillOverrides 写在 settings 文件中（项目级 .claude/settings.json 或用户级 /.claude/settings.json）： 适用场景： • 团队有几十个 Skills，但某个项目只想用其中几个 → 把其余设为 off • 某个 Skill 自动激活太频繁，但不舍得删 → 改为 user invocable only • 排查 Skill 冲突时，临时关闭部分 Skill 7.4 /skills 搜索过滤 当你安装了大量 Skills 时，直接输入 /skills 列表会很长。在较新版本中，/skills 支持搜索过滤： 例如 /skills comment 会过滤出名称或描述中包含 "comment" 的 Skill。这在管理十几个以上 Skill 时非常有用。 第八部分：FAQ（20个常见问题） Q1：Skill和Command有什么区别？ A：Command是"按钮"（触发器），Skill是"APP"（能力包）。Command用于显式触发，Skill用于封装知识和工具。两者通常配合使用：Command作为入口，Skill提供能力。 Q2：必须要SKILL.md吗？ A：是的，SKILL.md 是Skill的唯一必需文件。没有它Claude Code无法识别这是一个Skill。 Q3：SKILL.md可以是任意大小吗？ A：理论上可以，但建议控制在1000行以内。太大的SKILL.md会影响加载速度和AI理解。如果内容很多，考虑使用scripts/、config/等资源文件夹。 Q4：scripts支持哪些语言？ A：主要支持Python和Bash。推荐Python，因为生态好、跨平台、易维护。JavaScript也可以，但不如Python常用。 Q5：如何让Skill自动激活？ A：在SKILL.md的YAML Frontmatter中配置description字段。Claude Code会根据description判断何时激活。例如： Q6：可以有多个Skill吗？ A：可以。每个Skill是 .claude/skills/ 下的独立目录，可以有任意多个。 Q7：Skill之间会冲突吗？ A：如果description中描述的触发场景重复可能会冲突。建议每个Skill使用独特的触发场景描述。 Q8：如何更新Skill版本？ A：在SKILL.md的Markdown Body开头添加"版本历史"章节，记录每次变更。例如： Q9：SKILL.md多大合适？ A：建议单个SKILL.md不超过1000行。太长会影响加载速度和AI理解。大的Skill应该考虑拆分成多个子Skill或使用scripts/。 Q10：如何调试Skill？ A： 1. 验证YAML Frontmatter格式 2. 手动运行scripts/中的脚本测试 3. 检查description是否清晰 4. 查看Claude Code的Skill加载日志 Q11：Hot Reloading不生效怎么办？ A： 1. 确认修改的是SKILL.md而不是其他文件 2. 检查YAML Frontmatter格式是否正确 3. 尝试使用/compact压缩上下文后重试 4. 最后手段：重启Claude Code Q12：如何处理中文路径问题？ A：Windows上尽量避免中文路径。如果必须使用，确保SKILL.md文件编码为UTF 8（带BOM或不带BOM都可以，但要一致）。 Q13：Skill可以调用MCP吗？ A：可以。在SKILL.md的Markdown Body中可以引用MCP工具。Claude Code会自动识别并调用。 Q14：如何共享Skill给团队？ A：将整个 .claude/skills/你的skill/ 目录提交到Git仓库。团队成员克隆后即可使用。 Q15：Skill可以跨项目使用吗？ A：可以。将Skill放在全局配置目录（ /.claude/skills/）即可在所有项目中使用。 Q16：如何回退到旧版本Skill？ A：使用Git回退到旧版本的提交，或者在SKILL.md的版本历史中查看旧版本的内容。 Q17：SKILL.md中可以使用变量吗？ A：SKILL.md 支持一个特殊内置变量 ${CLAUDE SKILL DIR}，其他自定义模板变量不支持。 ${CLAUDE SKILL DIR} 变量说明： • 含义：指向当前 Skill 文件（SKILL.md）所在的目录路径 • 用途：在 SKILL.md 正文中引用同目录下的其他文件（模板、配置、示例等） • 示例： • 优势：使 Skill 可以组织为包含多个文件的目录结构，而不是将所有内容塞进一个 SKILL.md • 如果需要更复杂的动态内容，使用 scripts/ 中的脚本生成 Q18：如何测试Skill是否正常工作？ A： 1. 检查SKILL.md文件结构是否完整（YAML + Markdown） 2. 验证YAML Frontmatter格式 3. 手动测试scripts/中的脚本 4. 在Claude Code中测试触发词 Q19：Skill加载很慢怎么办？ A： 1. 减少SKILL.md的行数 2. 优化scripts/中的脚本性能 3. 检查是否有不必要的config/文件 Q20：如何学习更高级的Skill开发？ A： 1. 阅读公众号写作助手项目中的 SKILL.md 正文 2. 参考官方Skill示例 3. 实践中不断迭代优化 4. 理解渐进式披露和Hot Reloading机制 第九部分：附录 附录A：Skill目录快速创建脚本 macOS/Linux一键创建脚本： 附录B：SKILL.md完整模板 附录C：YAML Frontmatter快速参考 字段 类型 必填 说明 示例 name string ✅ Skill名称（小写、连字符） code commenter description string ✅ 触发场景描述 当用户要求"添加注释"时激活 字段 字段 类型 类型 必填 必填 说明 说明 示例 示例 name name string string ✅ ✅ Skill名称（小写、连字符） Skill名称（小写、连字符） code commenter code commenter description description string string ✅ ✅ 触发场景描述 触发场景描述 当用户要求"添加注释"时激活 当用户要求"添加注释"时激活 最佳实践： • name使用kebab case（小写+连字符） • description应该明确说明触发条件 • description中包含关键词会提高自动激活准确率 附录D：常用脚本示例 示例1：简单文本处理 示例2：JSON输出 恭喜完成Skills定制教程！ 现在你已经掌握了创建和管理Claude Code Skills的核心技能。 下一步建议： 1. 为你的工作领域创建一个实用的Skill 2. 参考公众号写作助手的SKILL.md架构设计更复杂的Skill 3. 与团队分享你的Skill，收集反馈持续优化 4. 深入理解Hot Reloading和渐进式披露机制 5. 如果团队已经积累了大量 Skills，可以进一步研究 SkillClaw：它关注跨用户、长期使用轨迹驱动的 skill 去重、合并、提质和共享，论文见 arXiv:2604.08377 SkillClaw arXiv:2604.08377 Skills定制完整指南：打造专属AI能力包的实战手册 课程信息 • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 预计学时：8 10小时 • 难度等级：⭐⭐ 入门级（有Claude Code基础即可） • 更新日期：2026年4月 • 适用版本：Claude Code v2.1.133（验证于 2026 05 08） • 前置要求：已完成Claude Code安装和Commands基础使用 • 🆕 专属内容：Hooks系统、Forked Sub Agents、Hot Reloading https://aiking.dev 课程信息 • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev https://aiking.dev • 预计学时：8 10小时 • 难度等级：⭐⭐ 入门级（有Claude Code基础即可） • 更新日期：2026年4月 • 适用版本：Claude Code v2.1.133（验证于 2026 05 08） • 前置要求：已完成Claude Code安装和Commands基础使用 • 🆕 专属内容：Hooks系统、Forked Sub Agents、Hot Reloading 本课学习目标 完成本课学习后，你将能够： 1. 理解Skills的核心价值：掌握Skills与Commands的本质区别和协作方式 2. 创建第一个Skill：5分钟内完成最简单的Skill配置并看到效果 3. 掌握SKILL.md结构：理解YAML Frontmatter和Markdown Body的编写规范 4. 掌握Skill目录结构：理解scripts、templates等资源组织方式 5. 掌握渐进式披露机制：理解元数据→指令→资源的三层加载逻辑 6. 利用Hot Reloading：快速迭代Skill，修改后自动生效 7. 配置Sandbox安全：正确设置文件系统、网络、内存等权限边界 8. 集成Python脚本：实现自动化工具扩展Claude Code能力 9. 上传自定义Skill：通过Web界面或API上传和管理Skill 10. 排查Skill故障：独立解决90%的常见配置和执行问题 11. 实战案例分析：深度理解企业级Skill架构设计 学习路径导航（先看这里！） 根据你的情况选择学习路径：这是一篇4000+行的长教程，不用全看！根据你的目标选择路径。 路径A：快速上手（30分钟） 适合人群：急着体验Skills，想快速创建一个看效果 只看这些章节（其他跳过）： 30分钟后你能达到：成功创建第一个Skill，Claude Code能识别并使用你的专属能力 路径B：完整学习（6 8小时） 适合人群：想深入理解Skills，掌握完整的开发能力 学习顺序：从头到尾所有章节 建议分段学习： • 第1天（2小时）：第1 3部分（理解+目录结构） • 第2天（2小时）：第4 5部分（提示词+脚本集成） • 第3天（2小时）：第6 7部分（实战案例+故障排查） • 第4天（1小时）：第8 9部分（FAQ+附录） 路径C：问题排查（10分钟） 适合人群：Skill配置出问题，需要快速解决 直接跳到这些章节： 使用方法： 1. 按 Ctrl + F 搜索你的错误信息关键词 2. 找到对应的Q&A 3. 按步骤解决 路径D：专项学习（30 60分钟/主题） 适合人群：已经会创建Skill，想学习特定功能 想学什么 看哪几节 预计时间 提示词工程 第四部分 1小时 Python脚本集成 第五部分 1.5小时 多步骤工作流 第六部分6.1节 45分钟 数据驱动架构 第六部分6.2节 1小时 企业级Skill设计 第六部分6.3节 1小时 想学什么 想学什么 看哪几节 看哪几节 预计时间 预计时间 提示词工程 提示词工程 第四部分 第四部分 1小时 1小时 Python脚本集成 Python脚本集成 第五部分 第五部分 1.5小时 1.5小时 多步骤工作流 多步骤工作流 第六部分6.1节 第六部分6.1节 45分钟 45分钟 数据驱动架构 数据驱动架构 第六部分6.2节 第六部分6.2节 1小时 1小时 企业级Skill设计 企业级Skill设计 第六部分6.3节 第六部分6.3节 1小时 1小时 术语表（小白必读） 在开始之前，先了解这些关键术语。用生活类比帮助理解： 术语 英文全称 通俗解释 生活类比 Skill • Claude Code的"能力包"，封装领域知识和工具 手机上的APP（如微信、淘宝） SKILL.md • Skill的核心定义文件（必需），包含YAML Frontmatter和Markdown Body APP的完整说明书（安装信息+使用手册） YAML Frontmatter • SKILL.md顶部的元数据区域（ 包裹），定义name和description APP的基本信息（名称、简介） Markdown Body • SKILL.md中YAML后的指令部分，详细说明使用方法 APP的详细操作手册 scripts/ • 脚本文件夹，存放可执行的工具程序 APP的功能模块代码 templates/ • 模板文件夹，存放输出格式模板 文档模板库 Progressive Disclosure 渐进式披露 按需加载：元数据常驻内存，指令和资源按需加载 微信：先看图标，点开看功能，用时加载详情 Hot Reloading • 修改SKILL.md后自动生效，无需重启 APP热更新，改完立即生效 Sandbox 沙箱 隔离执行环境，限制文件/网络访问，保证安全 APP的权限管理（只能访问相册） Commands 斜杠命令 显式触发的操作入口 APP里的功能按钮 YAML YAML Ain't Markup Language 配置文件格式，易读易写 填写表格（有固定格式） stdin/stdout Standard Input/Output 脚本的数据输入输出通道 快递的收发窗口 术语 术语 英文全称 英文全称 通俗解释 通俗解释 生活类比 生活类比 Skill Skill • • Claude Code的"能力包"，封装领域知识和工具 Claude Code的"能力包"，封装领域知识和工具 手机上的APP（如微信、淘宝） 手机上的APP（如微信、淘宝） SKILL.md SKILL.md • • Skill的核心定义文件（必需），包含YAML Frontmatter和Markdown Body Skill的核心定义文件（必需），包含YAML Frontmatter和Markdown Body APP的完整说明书（安装信息+使用手册） APP的完整说明书（安装信息+使用手册） YAML Frontmatter YAML Frontmatter • • SKILL.md顶部的元数据区域（ 包裹），定义name和description SKILL.md顶部的元数据区域（ 包裹），定义name和description APP的基本信息（名称、简介） APP的基本信息（名称、简介） Markdown Body Markdown Body • • SKILL.md中YAML后的指令部分，详细说明使用方法 SKILL.md中YAML后的指令部分，详细说明使用方法 APP的详细操作手册 APP的详细操作手册 scripts/ scripts/ • • 脚本文件夹，存放可执行的工具程序 脚本文件夹，存放可执行的工具程序 APP的功能模块代码 APP的功能模块代码 templates/ templates/ • • 模板文件夹，存放输出格式模板 模板文件夹，存放输出格式模板 文档模板库 文档模板库 Progressive Disclosure Progressive Disclosure 渐进式披露 渐进式披露 按需加载：元数据常驻内存，指令和资源按需加载 按需加载：元数据常驻内存，指令和资源按需加载 微信：先看图标，点开看功能，用时加载详情 微信：先看图标，点开看功能，用时加载详情 Hot Reloading Hot Reloading • • 修改SKILL.md后自动生效，无需重启 修改SKILL.md后自动生效，无需重启 APP热更新，改完立即生效 APP热更新，改完立即生效 Sandbox Sandbox 沙箱 沙箱 隔离执行环境，限制文件/网络访问，保证安全 隔离执行环境，限制文件/网络访问，保证安全 APP的权限管理（只能访问相册） APP的权限管理（只能访问相册） Commands Commands 斜杠命令 斜杠命令 显式触发的操作入口 显式触发的操作入口 APP里的功能按钮 APP里的功能按钮 YAML YAML YAML Ain't Markup Language YAML Ain't Markup Language 配置文件格式，易读易写 配置文件格式，易读易写 填写表格（有固定格式） 填写表格（有固定格式） stdin/stdout stdin/stdout Standard Input/Output Standard Input/Output 脚本的数据输入输出通道 脚本的数据输入输出通道 快递的收发窗口 快递的收发窗口 第一部分：Skills简介（10分钟理解） 1.1 Skills是什么 一句话理解：Skills是Claude Code的"能力APP"，把特定领域的知识、规则、工具打包成可复用的模块，让AI瞬间变成该领域的专家。 为什么需要Skills？ 没有Skills之前（每次都从零开始）： 有了Skills之后（专业知识即装即用）： 生活类比： • 没有Skills：每次打车都要从零教司机认路 • 有Skills后：安装了高德地图APP，司机直接导航到达（知识预装） Skills的核心价值 对比维度 没有Skills 有Skills后 知识积累 每次对话从零开始 领域知识预置，即用即专业 团队协作 每人都要教AI一遍 配置一次，全员共享 质量一致 输出质量随机 标准化流