用途
该技能用于诊断并修复 ZCode 客户端中 ZCode 技能（skill）的配置问题，目标是把任何技能问题归约为一个具体的修复动作。它特别区分“技能加载成功”与“技能触发”两个不同概念，先判断问题属于哪一类，再按流程排查。
主要能力
- 梳理技能发现顺序与优先级：显式配置的根目录、用户级
~/.zcode/skills、用户级~/.agents/skills、工作区.zcode/skills（从当前目录到仓库根，层级越深优先级越高）、工作区.agents/skills、启用的插件根（优先级最低）。同一层级内.zcode先于.agents扫描；技能身份是文件路径，同名技能在不同路径均会被发现，但只有发现顺序中的第一个会被加载，高优先级副本会遮蔽其余副本。以.开头的目录（.system除外）和node_modules会被跳过。 - 说明 SKILL.md 格式与两级失败模型：技能是包含 SKILL.md 的目录；frontmatter 是由
---分隔的扁平key: value行（缩进的键会被忽略；多行值用>或|）。可识别键为name、description、when_to_use、license、metadata。加载失败（技能被丢弃）的情况：frontmatter 存在但缺少name、缺少description，或description超过 1024 字符。加载但可能不触发的情况：完全没有 frontmatter（name 默认取目录名，description 为空，模型无从匹配）；格式错误的行会被跳过。 - 解释触发机制：技能的
name、description（截断至约 250 字符）和when_to_use会呈现给模型，由模型自行决定是否调用；没有关键词匹配器，清晰写明“何时使用”的 description 才能让技能对模型可发现。 - 提供检查方式：在客户端中，Settings → Skills 列出所有已发现技能及其分组，包括插件技能组；在输入框输入
/并打开 Skills 组可查看可用技能并按关键词搜索。作为代理时，按发现顺序读取各位置的 SKILL.md，实际加载的是第一个 frontmatter name（或插件的plugin:skill限定名）匹配的文件；若该文件不是你所编辑的文件，即找到了遮蔽。 - 给出常见陷阱的症状→原因→修复对照：未发现（目录错误）、点目录内被跳过、不触发（描述弱或为空）、被同名高优先级技能遮蔽、被配置禁用、frontmatter 解析错误或形状错误、缺少 SKILL.md、描述超过 1024 字符被丢弃、
.agents副本被同名.zcode副本遮蔽、插件技能因插件禁用或抑制而消失、路径与名称混淆、整个技能子系统关闭。 - 提供本地化排查流程（按顺序，找到原因即停止）：确认子系统是否开启（检查
~/.zcode/cli/config.json及工作区文件中的 skill 功能与skills.enabled，任一为 false 都会禁用发现）；确认是否被发现（检查 Settings → Skills，并在会话运行的工作目录下读取技能文件，发现是相对于该目录的）；检查加载失败（磁盘存在但未列出通常为 frontmatter 问题：缺少 name/description、描述过长或 frontmatter 行格式错误）；确定哪个文件实际胜出（按发现顺序遍历该名称，将第一个匹配的 SKILL.md 与所编辑文件对比，不一致即遮蔽）；检查是否被禁用（在两个配置文件中查找该技能的绝对路径及enable: false）；插件技能则确认插件已启用且未被抑制；已发现但不触发则检查 description/when_to_use 是否为空或过长/被截断。
使用方式
当 ZCode 客户端中技能未被发现、已安装但不触发、编辑后无效果或技能消失时，使用该技能按上述排查流程逐项检查配置文件、技能文件位置、frontmatter 内容与插件状态，并根据常见陷阱表定位原因并执行对应修复。
适用场景
适用于 ZCode 客户端内技能配置问题的诊断与修复，包括发现、加载、触发、遮蔽、禁用、插件相关及子系统开关等环节。
限制
该技能仅针对 ZCode 客户端的技能配置问题；不涉及其他客户端或非技能类故障。资料中未提供收费、价格、平台兼容性或效果保证等信息，暂未提供。