Skill Developer 故障排查

# 故障排除 - 技能激活问题 技能激活问题的完整调试指南。 ## 目录 - [技能未触发](#技能未触发) - [UserPromptSubmit 未建议](#userpromptsubmit-未建议) - [PreToolUse 未阻塞](#pretooluse-未阻塞) - [误报](#误报) - [钩子未执行](#钩子未执行) - [性能问题](#性能问题) --- ## 技能未触发 ### UserPromptSubmit 未建议 **症状：** 提问后，输出中没有出现技能建议。 **常见原因：** #### 1. 关键词不匹配 **检查：** - 查看 skill-rules.json 中的 `promptTriggers.keywords` - 关键词是否确实出现在您的提示词中？ - 记住：不区分大小写的子字符串匹配 **示例：** "keywords": ["layout", "grid"] - "how does the layout work?" → ✅ 匹配 "layout" - "how does the grid system work?" → ✅ 匹配 "grid" - "how do layouts work?" → ✅ 匹配 "layout" - "how does it work?" → ❌ 无匹配 **修复：** 在 skill-rules.json 中添加更多关键词变体 #### 2. 意图模式过于具体 **检查：** - 查看 `promptTriggers.intentPatterns` - 在 https://regex101.com/ 测试正则表达式 - 可能需要更宽泛的模式 **示例：** "intentPatterns": [ "(create|add).*?(database.*?table)" // 过于具体 ] - "create a database table" → ✅ 匹配 - "add new table" → ❌ 不匹配 (缺少 "database") **修复：** 拓宽模式： "intentPatterns": [ "(create|add).*?(table|database)" // 更好 ] #### 3. 技能名称拼写错误 **检查：** - SKILL.md 元数据中的技能名称 - skill-rules.json 中的技能名称 - 必须完全一致 **示例：** yaml # SKILL.md name: project-catalog-developer // skill-rules.json "project-catalogue-developer": { // ❌ 拼写错误: catalogue vs catalog ... } **修复：** 确保名称完全匹配 #### 4. JSON 语法错误 **检查：** bash cat .claude/skills/skill-rules.json | jq . 如果 JSON 无效，jq 将显示错误。 **常见错误：** - 多余的逗号 - 缺少引号 - 使用单引号代替双引号 - 字符串中未转义的字符 **修复：** 更正 JSON 语法，使用 jq 验证 #### 调试命令 手动测试钩子： bash echo '{"session_id":"debug","prompt":"your test prompt here"}' | npx tsx .claude/hooks/skill-activation-prompt.ts 预期：您的技能应出现在输出中。 --- ### PreToolUse 未阻塞 **症状：** 编辑应该触发的文件时...