这篇给你一条可复制的排障路线：先判断“有没有加载”，再判断“为什么没触发”。只要顺序对，绝大多数 Skill 问题 5-10 分钟就能定位。
本章完成标准
你完成后应该能独立定位 Skill 不生效问题，并区分是加载问题、依赖问题，还是会话快照问题。
先记住排障顺序
- 先看有没有被扫描到。
- 再看是否 eligible。
- 再看是否被同名覆盖。
- 最后看会话快照与日志。
步骤一：确认 Skill 被扫描到
openclaw skills list如果列表里没有它，优先查：
- 目录位置是否正确。
- 文件名是否为
SKILL.md。 - frontmatter 是否可解析。
- 是否在错误 workspace 下编辑。
步骤二：确认是否 eligible
openclaw skills list --eligible被扫描到但不 eligible，通常是门控没通过：
requires.bins缺命令。requires.env缺环境变量。requires.config对应配置未开启。os与当前平台不匹配。- Skill 被显式禁用。
步骤三：用 info 看真实加载源
openclaw skills info your_skill_name这一步用来确认：
- 当前实际加载的是哪个目录。
- frontmatter 解析出的字段是什么。
- 依赖门控条件是否符合预期。
步骤四：排查同名覆盖与优先级
同名 Skill 可能被优先级覆盖：
<workspace>/skills > ~/.openclaw/skills > bundled skills如果怀疑覆盖，先改成唯一名称，再次执行 skills info 验证。
步骤五：刷新会话快照并看日志
修改 Skill 后，旧会话可能仍用旧快照。建议：
- 新开会话再测。
- 必要时重启 gateway。
- 看日志定位解析或运行错误。
openclaw logs --follow
openclaw status --deep日志重点关注：frontmatter 错误、依赖缺失、配置键缺失、脚本路径错误、API 报错。
脚本型 Skill 的额外检查
脚本问题要与 Skill 触发问题分离：
- 先确认 Skill 可加载。
- 再单独运行脚本验证可执行性。
- 最后回到会话验证触发逻辑。
8 个最常见坑
SKILL.md命名错误。- frontmatter 格式错误。
description太空，模型难触发。- 依赖条件写了但本机不满足。
- 同名覆盖导致改错文件。
- 会话未刷新造成“假故障”。
- 脚本路径写死导致跨环境失败。
- 密钥注入位置错误导致 API 调用失败。
可直接复制的最小排障流程
openclaw skills list
openclaw skills list --eligible
openclaw skills info your_skill_name
# 新开会话后复测
openclaw logs --follow下一步建议
- 准备发布：看 发布到 ClawHub 完整流程。
- 回看规范：看 SKILL.md 写作规范。