技能（Skill）目录里已经有 SKILL.md，智能体（Agent）还是漏步骤。碰到这种情况，你可能会继续加规则：先做什么，必须做什么，最后再检查什么。
但还有一个问题没查：这轮任务里，它到底有没有拿到那份完整说明？
官方技能规范采用渐进式披露（Progressive Disclosure）：先提供名称与描述，激活后加载完整指令，再按任务需要读取资源。所以，文件存在与正文进入任务上下文，是两件可以分别检查的事。Agent Skills 规范
下面是一套排查与验收方法，示例用于说明步骤，没有新实测结果。
把“生效”拆成四个阶段
| 阶段 | 你需要确认什么 | 可以查看什么证据 |
|---|---|---|
| 文件存在 | 文件在预期位置，内容和元数据正确 | 文件路径、实际内容、修改版本 |
| 被客户端发现 | 当前会话能看到这个技能 | 客户端技能列表、配置诊断、可用技能目录 |
| 正文被加载 | 本轮执行拿到了完整指令 | 技能调用记录，或成功读取对应文件的工具记录；内置注入则看客户端提供的诊断 |
| 任务通过验收 | 执行动作和最终产物符合要求 | 工具结果、生成文件、字段检查、原始输入对照 |
这张表是排查顺序。具体证据取决于客户端：有的通过读文件加载，有的有专门的激活工具。官方接入指南列出了这些实现方式，并不要求所有客户端展示同一种日志。客户端技能接入指南
如果界面没有提供加载记录，就把这一项记为“缺少可见证据”，不要拿一句“我已使用该技能”替代它。
先查发现，再查触发
把技能放错目录，改多少正文都不会解决发现问题。先按你使用的客户端、版本核对路径与启用状态，避免把别人的目录结构直接套过来。
在 Codex 命令行界面（Command-Line Interface，CLI）和集成开发环境（Integrated Development Environment，IDE）扩展中，官方文档给出的入口是 /skills，也可以用 $ 提及技能。隐式匹配依赖 description。若自然语言请求没有触发，可以先做一次显式调用，缩小问题范围。OpenAI 技能文档
Claude Code 的排查文档也建议先确认技能是否可用，并尝试直接调用 /skill-name。它的 disable-model-invocation: true 用于禁止模型自动触发，仍允许用户直接调用。因此，“手动能用、自动不触发”还需要检查描述与调用策略。Claude Code 技能文档
显式调用通过，只说明这一条调用路径可以继续检查。它不能替代后面的产物验收。
用一个小任务验证，别直接上整套工作流
我建议先准备两份很短的本地发布说明，让技能汇总成表格。它不依赖网络、账号与浏览器，排查时少几个变量。
例如准备以下测试输入。文件名和内容都是示例，运行前需要自己创建：
release-a.md
新增：支持导出 CSV
已知问题：导出不包含附件
release-b.md
新增：支持批量重命名
已知问题：未提供
对应技能可以要求：只根据这两份文件汇总，输出文件名、新增功能、已知问题；缺失内容写“未提供”，保留明确列出的限制。
分别在两个新会话里运行：一轮自然语言请求，一轮显式指定技能。输入、模型设置与验收规则尽量保持一致。这是建议的对照方法，不代表已经测试通过。
请读取 release-a.md 和 release-b.md，汇总各自新增功能与已知问题。
每条结论保留来源文件名，不补充文件没有提供的信息。
显式指定时，在客户端支持的入口选择该技能，再提交同一任务。
检查执行记录与最终表格：有没有成功读取两份输入？有没有保留“导出不包含附件”？第二份的已知问题有没有写“未提供”？每行能否对应到原始文件？
这些检查点都可以独立核对。即使模型说“全部完成”，漏掉其中一项也要记下来。
让验收记录比“用了没有”更具体
下面这个记录模板可以直接复制。它是人工填写格式，不是任何客户端自带的日志或命令：
客户端与版本：
会话 / 运行标识：
技能名称与实际路径：
技能版本或修改时间：
调用方式：显式 / 隐式
发现证据：
加载证据：
输入读取结果：
产物位置：
验收：来源齐全 / 限制保留 / 缺失项未编造
失败发生在哪一步：
单次通过后，仍需要用不同任务验证。正常输入通过了，再加一份缺字段的文件，检查它会不会补出不存在的信息；再换一种表达方式，看自然语言触发是否仍然有效。
如果正文加载记录已经确认，而执行仍缺步骤，就继续查任务要求、工具可用性和验收规则。如果连发现证据都没有，先修目录或配置。按失败阶段修改，才知道这次改动解决了什么。
你使用的客户端能展示技能调用或文件读取记录吗？有没有遇到“能在列表找到，执行时却没读正文”的情况？欢迎带上客户端与版本讨论。
