安装了 Skill，为什么 AI 没有使用它？
按发现、选择、加载和执行四步排查。用最小周报示例与 Claude Code 官方安装说明，定位问题发生在哪一步。
你写好了 SKILL.md，让 AI 整理周报，却得到一份普通回答。这时很容易直接重写说明，但客户端没发现文件、AI 没加载正文，改再多规则也可能用不上。
可以按四步排查：发现是客户端把这个文件包列为可用；选择是 AI 判断本次任务要用它；加载是读取完整说明；执行是按说明完成任务。最后一步出错，也可能看起来像“没有触发”，但实际上文件已经加载了。
先确认当前客户端怎样安装
Agent Skills 格式规范要求文件夹中有 SKILL.md，并提供 name 和 description 等信息，但没有规定所有客户端都使用同一个安装目录。客户端接入说明也区分了先发现可用目录、再按任务加载完整文件的过程。
以具体客户端为例：2026 年 10 月 13 日核查的 Claude Code 官方说明列出项目位置 .claude/skills/<skill-name>/SKILL.md，以及个人位置 ~/.claude/skills/<skill-name>/SKILL.md。这里的路径只用于说明这个客户端；使用其他工具时，要先查看它自己的文档。
一个项目内的示例文件位置是：
.claude/skills/weekly-report/SKILL.md
最小内容可以这样写。本例整理英文周报，因此使用英文规则：
---
name: weekly-report
description: Draft a weekly status report from supplied work notes. Use when the user asks to summarize completed work, waiting items, and next work for the week.
---
# Weekly report
Ask for notes if none were supplied. Return Completed, Waiting, and Next work sections. Keep plans separate from completed work. Do not invent owners, approvals, dates, or results. Return a draft only. Do not send it.
检查实际文件名，不要只看编辑器标题：SKILL.md.txt 是另一个文件。检查两条 --- 之间的 YAML、文件夹名称与 name 是否一致，以及客户端是否设置了调用限制。格式正确，还需要放在客户端会扫描的位置，并让当前会话有权访问。
对比明确调用与日常请求
准备这份虚构记录：“Budget draft completed. Waiting for Lee's review. Invitations planned after approval; date not agreed.”意思是预算初稿完成，等待 Lee 审核，邀请计划依赖批准，日期未定。
先使用客户端规定的明确调用方式。在 Claude Code 中，可用 /weekly-report 调用本例，再附上记录。然后在新会话中只说“Turn these notes into a weekly status report”，不点名 Skill。分别查看可用的调用记录或会话信息。
| 观察到什么 | 下一步查什么 |
|---|---|
| 没有列出文件包，或无法明确调用 | 安装范围、文件名、元数据、客户端支持和会话发现情况 |
| 明确调用能加载，普通请求不加载 | 描述是否对应任务，以及选择行为 |
| 已读取全文，却编造批准状态 | 执行规则和事实检查 |
| 已读取全文，却打不开引用模板 | 加载之后的资源路径和访问问题 |
这些是排查线索，不是适用于所有工具的确定诊断。普通句子里提到 Skill 名称，也不保证每个客户端都把它当作明确调用。
让描述说清真实任务
“帮助写报告”没有说明报告类型和使用时机。上面的描述明确提到工作记录与每周状态汇报。如果缺少相关任务表述，就补上；不要为了提高加载次数，把邮件、表格和所有写作都塞进使用范围。
Claude Code 文档还列出了 disable-model-invocation 等影响自动选择的设置。先检查文件包是否有意关闭了自动调用，再优化描述。排查选择时尽量保持周报规则不变，避免同时修改两件事，分不清是什么产生了影响。
保存客户端版本、安装位置、原始请求和实际加载记录或错误。“AI 说自己用了”不足以确定成功；完整 SKILL.md 的读取记录或客户端调用记录更有帮助。工具不提供这些信息，就标记为加载情况无法核实，不要直接认定成功或失败。
确认能加载后，再用多组输入检查输出。AI 可能读了说明，却仍然新增没有依据的事实。安装检查解决能否访问，输出检查则要回到工作记录本身。
参考资料
- Agent Skills specification：文件夹与元数据要求。
- Adding Skills support：发现和加载的过程。
- Claude Code Skills：客户端特定的安装位置、调用方式和调用控制。
