Skill 没生效：亲手复现四种故障，再逐层修好

同一句“没生效”，可能是文件名错了、技能没被发现、请求没触发，或者输出根本不合格。本课用一个极小的文件分类 Skill 做实验，一次只改变一个条件，让你知道应该改哪一层，而不是不停重装工具。

先按 Claude Code 安装篇 或 Codex 安装篇 配好其中一种本地 CLI。本文两种路径都列出，但只选你实际使用的一条。不要同时把同名技能复制到多个位置来碰运气。

1. 建立一个正常样例作为对照

新建独立练习目录 C:\ai-practice\skill-lab。若使用 Claude Code，建立 .claude\skills\kg-file-label\SKILL.md；若使用 Codex，建立 .agents\skills\kg-file-label\SKILL.md。开启文件扩展名显示，用纯文本编辑器保存以下完整内容：

---
name: kg-file-label
description: 依据用户给出的文件名后缀，区分PDF文档、ZIP压缩包和Markdown文本。用于下载文件的初步类型整理，不判断安全性、不执行或解压文件。
---

# 文件类型标签

只处理用户粘贴的文件名，不读取真实文件。
按最后一个后缀分类，忽略后缀字母大小写：
- .pdf：PDF文档
- .zip：ZIP压缩包
- .md：Markdown文本
- 其他或无后缀：无法按本课规则分类
输出两列：原文件名、类型。保留原文件名不变。
不能根据文件名推断内容安全、许可证或收费情况。
不联网、不运行命令、不改文件、不执行解压。

这是本课原创教学 Skill，不是某个下载包的原始入口。使用前记录工作目录与 claude --version 或 codex --version；npm 安装的 Windows Codex 也可运行 codex.cmd --version。

在 Claude Code 对话里使用 /kg-file-label；在 Codex 的 /skills 中选择它，或使用 $kg-file-label。附上输入：

请分类这些文件名：
guide.PDF
skill.v2.zip
README.md
setup.exe

人工教学预期为：guide.PDF 是 PDF 文档，skill.v2.zip 是 ZIP 压缩包，README.md 是 Markdown 文本，setup.exe 无法按本课规则分类。不应说最后一个文件安全或可以直接运行。先让正常样例通过，再开始故障实验。

2. 第一种故障：入口文件名错了

停止当前调用，在文件管理器把练习入口改名为 SKILL.md.txt，保留文件内容。重开同一目录的会话，观察它是否还能作为技能出现。如果旧会话保留了刚才加载的内容，不要凭旧上下文判断新安装状态。

在 PowerShell 中验证精确路径，选对应工具的一条：

# Claude Code项目
Test-Path -LiteralPath '.\.claude\skills\kg-file-label\SKILL.md'
# Codex项目
Test-Path -LiteralPath '.\.agents\skills\kg-file-label\SKILL.md'

结果应为 False。用编辑器打开 SKILL.md.txt 能读到文字，不证明宿主会把它当入口。修复方式只是恢复精确文件名 SKILL.md，然后重新检查。不要重装 Claude Code 或 Codex。

如果这里仍返回 True，说明你改的不是正在检查的那份文件，或目录里同时存在两份入口。先对齐位置，不能直接进入下一步。

3. 第二种故障：目录多包了一层

恢复正常样例后，在 kg-file-label 内新建 download 文件夹，只把入口移入这个子目录，使它变成：

skills/
└─ kg-file-label/
   └─ download/
      └─ SKILL.md

这是模拟“把外层归档当成技能目录”的常见错误。不要预设所有宿主、所有版本都会以相同方式递归扫描。关键是核对实际发现路径和名字：我们需要的入口是 kg-file-label/SKILL.md，而不是靠偶然发现深层文件才可用。

把文件恢复到规定层级，保持文件夹名与 name 一致，重新打开技能选择列表。如果列表仍缺失，再检查 YAML：开头第一行必须是 ---，结束元数据也需要单独一行 ---，不要把整份文档包在三反引号里保存。

Codex 本地技能规范要求 name 和 description。Claude Code 的当前文档允许省略一些字段，但本课保留两者，以便理解且便于跨宿主复用。不要把一种工具“宽容地接受”误写成另一种工具也必然接受。

4. 第三种故障：找得到，却没有自动触发

确保明确调用能成功后，在新会话中不用技能名称，只问：“帮我看一下这些东西。”附上同样的文件名。这样的任务太模糊，工具可能按普通问题回答，不能据此判定安装失败。

把请求改成：“请按文件名最后一个后缀，整理成原文件名与类型两列，不判断安全性。”它与描述更接近，但自动选择仍受宿主配置、其他技能和上下文影响，不承诺每次都会触发。

如果你就是要验证某个技能，明确调用更合适。检查本轮实际加载记录与入口，而不是只看回答开头有没有“我已使用 Skill”。在 Claude Code 中，disable-model-invocation: true 会限制自动调用；user-invocable: false 则影响用户从命令入口调用，不是同一个开关。

Codex 的隐式调用策略可以位于 agents/openai.yaml，例如 policy.allow_implicit_invocation: false；明确 $技能名 的调用仍是另一条路径。不要把 Claude 的字段粘进 Codex，认为两边效果相同。

5. 第四种故障：确实调用了，但答案错了

给出下面这组新增输入，专门检查“按最后一个后缀”的规则：

report.pdf.zip
REPORT.PDF
README

人工预期是 ZIP 压缩包、PDF 文档、无法按本课规则分类。report.pdf.zip 中间虽然出现 .pdf，最后一个后缀仍是 .zip；README 没有后缀，不能因它常见就自动归类为 Markdown。

反例输出“report.pdf.zip 是 PDF，README 是 Markdown”说明规则执行不合格，不代表技能入口没有找到。反馈要指出两项误判，要求按最后后缀重算；如果频繁发生，可以在 Skill 正文增加这组明确的正反例，再用新会话复测。

这也解释了为什么不能只用一条最简单输入验收。正常、大小写、复合后缀、无后缀四种材料，分别检验了不同规则。

6. 写一份别人能接着排查的记录

可以把以下模板填在自己的本地笔记中，分享前遮住私人路径：

宿主与版本：
工作目录（已脱敏）：
安装范围：当前项目 / 个人 / 插件
入口相对路径：
精确路径检查：True / False
技能列表是否出现、显示的来源：
明确调用方式及本轮加载记录：
最小输入：report.pdf.zip、REPORT.PDF、README
期望：ZIP、PDF、无法按规则分类
实际输出与具体差异：
最近唯一改动及恢复后的结果：

如果发现同名技能来自个人目录、项目和插件，先确认来源规则：Claude Code 个人技能可能优先于项目技能；Codex 同名项不会自动合并。不要为了“让新版本赢”删除未知目录。

本课只处理纯指令练习。真实资源若需要脚本、MCP 或外部服务，还应单独验证依赖是否成功，但不能把安装更多依赖作为本课的修复方法。出现要上传无关材料或扩大权限的动作时先停下，核对是否与原任务相关。

本文按官方发现与调用规则设计实验，没有替你运行模型。保留正常样例，逐次制造、恢复单一故障，才更容易看出因果。接下来可学 制作自己的 Skill 或 更新与移除。