1. 为什么 SKILL.md 放好了Claude 还是说读不到你大概率遇到过这个场景照着文档在项目里建了.claude/skills/my-skill/SKILL.mdYAML 头也写了重启了 Claude Code结果问它「你能看到哪些 skills」它一脸无辜地回你「我没有看到任何自定义 skills」。这时候你开始怀疑人生——是路径错了是文件名大小写问题还是模型压根没加载先给结论Claude 读不到 skills90% 不是模型的问题而是「文件没被扫描到」或「扫描到了但没进上下文」这两件事之一。而这两件事恰好可以用两个动作区分开read_file和list-skills。这两个动作的区别很关键。read_file是「我明确告诉你路径你去读这个文件」它验证的是文件系统层面能不能访问list-skills是「你告诉我你当前注册了哪些技能」它验证的是技能注册表层面有没有被加载。如果read_file能读到内容、但list-skills里没有那问题就锁定在「扫描/注册」环节而不是文件本身。反过来如果read_file都读不到那就是路径或权限问题跟 skills 机制无关。我试过在一个多级子目录的项目里排查这个问题当时 SKILL.md 放在packages/foo/.claude/skills/下但 Claude Code 的工作目录是仓库根目录结果list-skills死活不显示。后来把 skills 挪到根目录的.claude/skills/才被扫到。这个坑很典型下面会展开。这篇文章聚焦的就是这条排查路径从目录结构、SKILL.md 最小示例到read_file与list-skills的返回差异再到逐项验证动作。适合已经在用 Claude Code、想确认 skills 是否真正进入上下文的同学。如果你还没配好底层模型通道后面也会给一段可复制的接入配置保证请求能稳定打到模型上不然排查到一半发现是网络层的问题就很亏。核心检索词先明确Claude skills 可见性排查本质是确认SKILL.md是否被正确扫描并注册进list-skills的输出里。下面按「先确认能读到文件 → 再确认注册表里有 → 最后确认触发时进上下文」三层来拆。2. 前置让请求稳定打到模型再谈 skills 排查排查 skills 之前有个容易被忽略的前提你的请求得真的能到模型。如果底层通道不稳定list-skills返回空可能根本不是 skills 的问题而是请求压根没成功。所以这一步先把模型接入配好再进入 skills 排查能省掉大量误判。TaoToken 在这里的角色是提供一个兼容 Anthropic 接口的通道Claude Code、Cline 这类工具可以直接把 Base URL 指过来。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM配置里直接用。配置的核心是三件套Base URL API Key Model ID。这三个缺一不可尤其是 Model ID写错了会直接报模型不存在而不是 skills 读不到。下面给一段 Claude Code 场景下可复制的配置思路。先拿 Key进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个复制出来。文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的接入说明。Claude Code 的环境变量方式大致是这样macOS/Linux 写进~/.zshrc或~/.bashrcexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key export ANTHROPIC_MODELclaude-sonnet-4-5Windows 用 PowerShell 的话$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的key $env:ANTHROPIC_MODELclaude-sonnet-4-5注意 Model ID 要跟你实际能用的模型对齐别照抄。配完之后先跑一个最简单的对话验证通道通不通再进 skills 排查。如果这一步就报 401那先解决鉴权别往下走。提示如果你用的是 Cline 或 Claude Code 的 settings 文件方式配置项名字可能不同但三件套的逻辑一样——Base URL 指向https://taotoken.net/apiKey 用控制台生成的Model ID 填你选的模型。Cline 的 MCP 配置里如果出现 skills 相关路径也要保证 Base URL 和 Key 是同一套。通道通了之后list-skills返回空才有排查价值。否则你分不清是 skills 没加载还是请求没成功。这一步是很多教程跳过的但实际排查里它能帮你排除掉一半的干扰项。3. 可复制配置目录结构、SKILL.md 最小示例与 settings 片段这一节给可直接抄的配置。先把目录结构摆清楚这是最容易出错的地方。项目级 skills 路径只对当前项目生效your-project/ ├── .claude/ │ └── skills/ │ └── my-skill/ │ └── SKILL.md ├── src/ └── package.json全局级 skills 路径所有项目可用macOS/Linux~/.config/claude/skills/ └── my-skill/ └── SKILL.md两个关键点第一SKILL.md必须区分大小写写成skill.md或Skill.md都可能扫不到第二每个 skill 必须独立文件夹不能把多个 SKILL.md 平铺在 skills 目录下。SKILL.md 的最小示例YAML 前置元数据是必须的--- name: pdf-extractor description: 处理 PDF 文件时提取文本数据并做结构化分析适用于 PDF 数据分析、报表解析场景 --- # PDF Extractor 当用户要求分析 PDF 内容时按以下步骤执行 1. 使用 read_file 读取目标 PDF 路径 2. 提取文本后按段落切分 3. 输出结构化 JSONname用小写加连字符别用下划线或空格长度控制在 64 字符内description要写清楚触发场景因为list-skills返回的就是这个描述模型靠它判断什么时候该调用。描述写得含糊模型就算注册了也不会主动用。如果你用 Claude Code 的 settings 方式管理settings.json里可以显式声明 skills 目录路径按你实际项目改{ skills: { enabled: true, paths: [ .claude/skills, ~/.config/claude/skills ] }, permissions: { allow: [ read_file, list-skills ] } }这段 JSON 的作用是双重的paths告诉 Claude Code 去哪扫permissions.allow保证read_file和list-skills这两个工具不会被权限拦掉。很多人list-skills返回空其实是权限没开工具调用被静默拒绝了。注意paths里的相对路径是相对于工作目录的不是相对于 settings.json 所在目录。如果你在子目录启动 Claude Code.claude/skills就会指向子目录下的路径根目录的 skills 自然扫不到。这是前面提到的那个坑的根因。配置写完重启 Claude Code 让它重新扫描。重启这一步别省热加载不一定生效。4. 验证请求用 read_file 和 list-skills 的返回差异定位问题配置就位后进入核心验证环节。这里的关键是分两步问对比返回而不是笼统地问「你能看到 skills 吗」。第一步验证文件系统可读性。直接让 Claude 用read_file读你那个 SKILL.md 的绝对路径用 read_file 工具读取 /你的项目绝对路径/.claude/skills/my-skill/SKILL.md 的内容如果返回了正确的 YAML 头和正文说明文件存在、路径对、权限够。如果这一步就失败报文件不存在或权限拒绝那问题在文件系统层跟 skills 注册无关去检查路径拼写和文件权限。第二步验证技能注册表。让 Claude 枚举当前注册的技能列出所有可用的 skills或者在 Claude Code 里直接执行斜杠命令/list-skills预期返回应该包含你的 skill 名称和描述类似可用 skills: - pdf-extractor: 处理 PDF 文件时提取文本数据并做结构化分析...对比两种返回问题就定位了read_file 结果list-skills 结果问题定位成功读到内容列表里有该 skill一切正常skills 已进上下文成功读到内容列表为空/没有该 skill扫描或注册环节出问题检查 paths 和工作目录读取失败列表为空文件系统层问题检查路径、大小写、权限读取失败列表里有该 skill罕见可能是缓存了旧路径重启并清理缓存实测下来第二种情况最常见文件明明在read_file也能读但list-skills就是不显示。这时候八成是工作目录和 skills 路径不匹配或者settings.json的paths没配对。第三步验证触发时是否进上下文。注册成功不代表触发时一定加载。用一个明确的触发词测试pdf-extractor 帮我分析这个 PDF如果 skill 绑定了斜杠命令也可以直接/pdf-extractor。观察响应里有没有体现 SKILL.md 里定义的步骤或者看工具调用日志里有没有加载 SKILL.md 的记录。这一步验证的是「注册 → 触发 → 进上下文」的完整链路。如果前两步都过了、第三步不生效那问题在description的触发描述上——模型注册了但判断不出什么时候该用。把 description 改得更具体加上明确的场景关键词。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth排查过程中会撞到几类典型报错这里逐个对照。401 Unauthorized。这个跟 skills 无关是鉴权失败。检查ANTHROPIC_API_KEY是不是复制完整了有没有多余空格Key 是不是在控制台被删了。如果用的是 TaoToken去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一个。401 出现时list-skills必然返回空因为请求根本没到模型别误判成 skills 问题。local proxy failed / connection refused。这是本地代理或网络层的问题请求没出去。检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api注意结尾不要多加斜杠或路径以及本机网络能不能访问这个地址。这类报错下 skills 排查没有意义先把通道修通。reading choices 相关报错。通常出现在响应解析阶段说明请求发出去了但返回格式不对。常见原因是 Model ID 写错或者客户端把非 Anthropic 格式的响应当 Anthropic 解析。核对ANTHROPIC_MODEL是否为你实际可用的模型 ID别填一个不存在的名字。OAuth 相关报错。如果你用的是 Claude Code 的 OAuth 登录方式同时又配了ANTHROPIC_API_KEY两者可能冲突。排查 skills 时建议统一用一种鉴权方式要么全走 Key要么全走 OAuth别混用。混用时list-skills可能因为鉴权上下文混乱而返回异常。skills 列表为空但无报错。这是最隐蔽的。没有报错说明请求成功了但注册表是空的。按顺序检查工作目录是不是 skills 的父目录、settings.json的paths对不对、SKILL.md大小写对不对、YAML 头有没有语法错误比如缺了---闭合。YAML 头写错会导致整个 skill 被静默跳过不报错但也不注册。提示排查时养成「先看有没有报错再看返回内容」的习惯。有报错先修报错没报错再对比read_file和list-skills的返回差异。这个顺序能避免在错误的层面上浪费时间。如果确认是通道层的问题需要换配置接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的完整参数说明。长期跑编码和 Agent 任务的话Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合需要稳定长会话的场景。6. 把 skills 排查变成固定动作最后给一套可以固化成习惯的排查顺序下次再遇到「Claude 读不到 skills」直接照着走先确认通道通不通——跑一句普通对话有 401 或连接错误就先修通道别碰 skills。通道通了之后用read_file读 SKILL.md 的绝对路径验证文件系统层。读到了再用list-skills或「列出所有可用的 skills」验证注册表。注册表里有再用触发词验证上下文加载。三层逐层过哪层断了问题就在哪层。目录结构上记住三条SKILL.md区分大小写、每个 skill 独立文件夹、项目级路径相对于工作目录。settings.json里paths和permissions.allow都要配前者管扫描后者管工具调用权限。YAML 头写错会静默跳过不报错但也不注册所以写完 SKILL.md 先用read_file确认内容完整。模型对话验证可以在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 快速试一下触发效果确认 description 写得够不够具体。整套流程跑顺之后skills 排查就从玄学变成了三步定位不用再靠重启和祈祷。
