语音摘要 — 点击播放以跟读：正在朗读的行会保持在顶部附近。
你将学到什么
预计时间：15分钟
通过本课程你将掌握：
- 使用技能验证器在调试前发现结构性问题
- 诊断并修复常见的技能触发和加载问题
- 解决企业、个人、项目和插件技能之间的优先级冲突
- 调试运行时错误，包括缺失依赖项、权限和路径问题
技能故障排除
(4分钟)
当技能未按预期工作时，问题通常可分为几类常见情况。本视频将逐一讲解——从技能未触发到优先级冲突再到运行时故障——并为你提供系统化的排查方法。你还将了解技能验证工具及如何使用claude --debug诊断加载问题。
关键要点
- 首先使用技能验证工具——它能在你浪费时间调试其他问题前发现结构性问题
- 如果技能未触发，原因几乎总是描述问题——添加与你实际请求方式匹配的触发短语
- 如果技能未加载，检查SKILL. md是否位于命名目录内（而非技能根目录）且文件名必须完全匹配SKILL. md
- 如果错误技能被调用，说明你的描述过于相似——让它们更具区分度
- 对于运行时错误，检查依赖项、文件权限（chmod +x）和路径分隔符（统一使用正斜杠）
使用技能验证器
首先尝试使用代理技能验证命令。安装步骤因操作系统而异，但使用uv是最快捷的设置方式。
安装完成后，可导航至你的技能目录或从任意位置运行命令。验证器能在你调试其他问题前发现结构性问题。
技能未触发
技能存在且通过验证，但Claude未按预期调用。原因几乎总是描述问题。
Claude使用语义匹配，因此你的请求需要与描述含义重叠。如果重叠不足，则无法匹配。解决方法：
- 根据实际请求方式检查你的描述
- 添加用户实际会说的触发短语
- 用多种变体测试："帮我分析这个"、"为什么这么慢？"、"优化速度"
- 如有变体无法触发，将这些关键词加入描述
技能未加载
如果询问Claude"有哪些可用技能"时你的技能未显示，请检查以下结构要求：
- SKILL. md文件必须位于命名目录内，不能直接在技能根目录
- 文件名必须完全匹配SKILL. md——"SKILL"全大写，"md"全小写
运行claude --debug查看加载错误。寻找提及你技能名的消息，有时这会直接指出问题所在。
错误技能被调用
如果Claude调用了错误技能或在相似技能间混淆，说明你的描述可能过于相似。让它们更具区分度。尽可能具体的描述不仅能帮助Claude判断何时调用你的技能——还能避免与其他相似技能的冲突。
技能优先级冲突
如果你的个人技能被忽略，可能因为存在同名企业或更高优先级技能。
例如，如果存在企业版"code-review"技能而你也有个人版"code-review"技能，企业版总会优先。解决方案：
- 将你的技能重命名为更独特的名称（通常更简单）
- 联系管理员协商企业技能
插件技能未显示
安装了插件但看不到其技能？清除缓存，重启Claude Code并重新安装。
如果技能仍未显示，可能是插件结构有误。此时验证工具将发挥最大价值。
运行时错误
技能已加载但执行失败。常见原因：
- 缺失依赖项：如果技能使用外部包，必须预先安装。在技能描述中添加依赖信息以便Claude知晓需求。
- 权限问题：脚本需要执行权限。对技能引用的任何脚本运行chmod +x。
- 路径分隔符：统一使用正斜杠，即使在Windows系统。
快速排查清单
- 未触发？ 优化描述并添加触发短语
- 未加载？ 检查路径、文件名和YAML语法
- 错误技能？ 增强描述区分度
- 被覆盖？ 检查优先级层次并考虑重命名
- 插件技能缺失？ 清除缓存并重新安装
- 运行时故障？ 检查依赖项、权限和路径
课程反思
- 你在工作中是否遇到过这些故障场景？哪个解决方案最能节省你的时间？
- 你会如何建立技能共享前的验证流程？
课程总结
恭喜完成《代理技能入门》！你已学会在Claude Code中创建、配置、共享和排查技能问题。当你开始为工作流构建技能时，请记住最佳技能源于真实痛点——从你最常重复的指令开始。
反馈
我们期待了解你如何使用技能，以及对本课程的任何反馈。点击此处分享你的意见。