本文摘要技能路径正确却从不触发命中不稳定让排查反复落空。description写成功能清单不匹配意图三步测试可定位失准环节。边界是单技能调优需 100% 确定触发时应改用显式调用。一、问题与结论你在~/.claude/skills/db-optimizer/SKILL.md写了一份自认详尽的技能frontmatter 三件套齐全放进去后会话里却始终等不到它。换成另一句问法偶尔闪现一次下次又哑了——这是触发不稳定不是没写。结论先行命中由三个触发条件共同决定name的区分度、description的语义方向、keywords的场景覆盖面。多数不触发属于第二项描述写成了我能做什么而模型在匹配你遇到了什么问题。当前目录结构项目级为例your-repo/ ├── .claude/ │ └── skills/ │ ├── db-optimizer/ │ │ └── SKILL.md │ └── pg-index-debugger/ │ └── SKILL.md └── CLAUDE.md用户级技能在~/.claude/skills/name/SKILL.md。SKILL.md的 frontmatter 会随 Claude Code 版本变化是否支持显式keywords列表以当前安装版本文档为准本文字段按社区通用实践整理示例输出均标注验证状态。二、排查与选择依据结论三步测试能把不触发归因到具体一环不要一上来改文件。Step 1确认技能已加载。ls.claude/skills/*/SKILL.md预期输出.claude/skills/db-optimizer/SKILL.md .claude/skills/pg-index-debugger/SKILL.md文件不在列表 → 查路径与目录名一致性在列表 → 进 Step 2。会话内再用/help或当前版本的技能列表命令确认技能名出现命令与输出以实际版本为准本文未验证。Step 2复制description原句直接发给会话。原句能触发而自己的话不触发 → 文本有效但覆盖面不足进 Step 3原句也不触发 →name或description本身有问题回到第三节修复。Step 3用你平时会自然敲出的说法测试。测试输入类型触发结果归因与修复description原句触发覆盖面不足补口语化场景句自然口语不触发description缺场景描述自然口语触发了别的技能name区分度不够提高特异性替代方案与取舍方案选择条件代价边界显式调用/pg-index-debugger需要 100% 确定触发打断自然语言流每次手动敲不适合探索式排查CLAUDE.md 常驻指令规则无条件生效占用上下文所有对话都加载不适合条件触发型技能Hooksettings.json格式化、lint 等确定性动作无法处理语义条件不适合需要推理的诊断当技能正文极短、按上述方法调完仍不命中、或团队要求行为完全可复现时不该继续在description上耗时间直接改用显式调用。三、关键原理Claude Code 是通过自然语言命令与代码库交互的终端工具技能没有传统函数调用入口命中是语义匹配的概率结果。三个字段对命中率的影响分工如下字段对命中的作用常见失误name技能标识候选池内区分度db-optimizer、code-linter这类泛化名description权重最高快速筛选的主文本写成 analyze / recommend 功能清单keywords覆盖同义词与口语表述只有领域词没有问题场景句功能清单描述与用户意图的语义方向相反前者陈述能力后者陈述故障。把我能做什么改写成你会遇到什么问题是提高命中率成本最低的一步name与keywords更多起辅助确认作用。四、可运行示例环境Claude Code当前安装版本项目根目录已有.claude/skills/。目标是索引问题稳定命中。文件.claude/skills/pg-index-debugger/SKILL.md--- name: pg-index-debugger description: 当开发者遇到 PostgreSQL 索引不生效、全表扫描、EXPLAIN ANALYZE 显示 Seq Scan 而非 Index Scan、建了索引查询反而更慢、 pg_stat_user_indexes 中 idx_scan 为 0 等问题时使用。 诊断统计信息误判、列顺序不匹配、隐式类型转换、索引膨胀。 keywords: - 索引失效 - Index Scan vs Seq Scan - EXPLAIN ANALYZE 索引 - query slow after index --- # PostgreSQL 索引诊断 1. EXPLAIN ANALYZE 确认是否出现 Seq Scan 2. pg_stat_user_indexes 查 idx_scan 是否为 0 3. 核对 WHERE 列顺序与索引定义 4. 检查统计信息是否过时、是否存在隐式类型转换 输出诊断结论一句话 EXPLAIN 片段 修复命令。操作步骤保存文件 → 开新会话 → 输入 Step 3 的自然口语12 万行的表加了复合索引还是走 Seq ScanEXPLAIN ANALYZE 里 cost0.00..18500预期输出技能被加载回答先给出 Seq Scan 归因再附EXPLAIN ANALYZE片段与ANALYZE/ 重建索引命令。实际输出未验证——本文未在本机执行 Claude Code 会话以上为按字段设计推理的预期行为。验证方法开新会话连续三次输入同一句话观察技能是否每次都在响应链路中出现。常见失败及修复沿用name: db-optimizer的旧文件时Step 2 原句能触发、Step 3 口语不触发。原因是description写成 “PostgreSQL and MySQL query performance optimization tool” 这类能力陈述keywords只有database optimization领域词。修复name收窄为pg-index-debugger描述首句改为问题场景句。五、验证结果与边界代价有三。其一技能按需加载只在命中后才读正文但技能列表元数据常驻上下文description越长、技能堆到几十个列表本身就越推高 token。其二场景句堆叠过多会与同领域技能互相抢命中覆盖面和精确度是直接冲突的。其三模型升级后语义理解变化同一份文件的命中行为可能变好也可能变差需重跑三步测试。不适用的边界路径与加载顺序问题不在本方法范围内项目级与用户级技能在部分版本中合并优先级不同先确认加载需要外部工具集成走 MCP Server确定性动作走 Hook。以上示例输出与命中行为均未在本机验证字段以当前版本官方文档为准。参考资料anthropics/claude-codeaffaan-m/ECCfarion1231/cc-switch