Claude Code Skill 突然「用不了」？一次完整的排查实录

环境：macOS + Claude Code 2.1.199（实际运行进程为 2.1.191）
现象：/reload-skills 一直显示「13 skills available (no changes)」，但磁盘上明明有上百个 skill，调用时也基本不生效。

本文完整记录这次排查的思路、证据链和最终根因，方便你遇到类似问题时按图索骥。

---

一、问题现象

• ~/.claude/skills/ 下手动放了 100+ 个 skill 目录，每个都含 SKILL.md
• 启动 Claude Code 后，/reload-skills 始终报「13 skills available」，对不上实际数量
• 用 --debug-file 抓日志，看到的关键行是：

[DEBUG] Loading skills from: managed=/Library/Application Support/ClaudeCode/.claude/skills,
        user=/Users/chenzc/.claude/skills,
        project=[/Users/chenzc/git/grain_scanner/.claude/skills]
[DEBUG] [reduced mode] Skipping skill dir discovery
[DEBUG] Total plugin workflows loaded: 0
[DEBUG] getSkills returning: 0 skill dir commands, 0 plugin skills, 20 bundled skills, 0 builtin plugin skills

关键异常：[reduced mode] Skipping skill dir discovery —— 直接跳过了 skill 目录扫描，导致 0 skill dir commands 被加载。

---

二、排查思路

排查任何「配置/资源没生效」类问题，本质上就三步：

1. 磁盘上到底有没有 —— 先确认资源文件本身是否完好
2. 进程有没有看到 —— 看程序实际加载行为（而不是看 UI 显示）
3. 为什么没看到 —— 找出阻断加载的开关/条件

我把这三步对应到本次问题：

步骤	命令 / 证据	结论
磁盘有没有	ls ~/.claude/skills/ | wc -l → 102	✅ 文件完好，且每个目录都有 SKILL.md
进程看到没	debug log → 0 skill dir commands	❌ 一个都没加载
为什么没看到	log → [reduced mode] Skipping skill dir discovery	🔑 进入「精简模式」，扫描被跳过

剩下的问题是：「reduced mode」是谁触发的？

---

三、定位根因

3.1 从二进制里挖出 mode 的官方定义

reduced mode 不是 Claude Code 文档里直接讲的词，但它是 Mach-O 二进制内的字符串。直接 strings 出来：

strings /Users/chenzc/.local/share/claude/versions/2.1.199 \
  | grep -iE "reduced mode|CLAUDE_CODE_SIMPLE|Skipping skill"

挖到一段关键说明：

Minimal mode: skip hooks, LSP, plugin sync, attribution, auto-memory,
background prefetches, keychain reads, and CLAUDE.md auto-discovery.
Sets CLAUDE_CODE_SIMPLE=1. Anthropic auth is strictly ANTHROPIC_API_KEY
or apiKeyHelper via --settings (OAuth and keychain are never read).
3P providers (Bedrock/Vertex/Foundry) use their own credentials.
Skills still resolve via /skill-name. Explicitly provide context via:
--system-prompt[-file], --append-system-prompt[-file], --add-dir,
--mcp-config, --settings, --agents, --plugin-dir.

翻译一下重点：

• CLAUDE_CODE_SIMPLE=1 会触发 Minimal mode（精简模式），二进制里日志层面也叫 reduced mode
• 在该模式下：skill 目录扫描被跳过，hooks、LSP、插件同步、auto-memory、CLAUDE.md 自动发现等也全部跳过
• skill 只能通过 显式 /skill-name 调用 —— 但前提是 Claude 自己知道这个名字，目录没扫它根本不知道有哪些可用

也就是说：/reload-skills 显示「13」是个误导性的 UI 数字，真正决定加载行为的是 debug log 里的 getSkills returning，那里清清楚楚写着 0。

3.2 顺着环境变量找「谁干的」

先看当前进程环境变量：

env | grep -iE "claude|skill|simple|reduce"

输出里有：

CLAUDE_CODE_SIMPLE=1
CLAUDE_CODE_CHILD_SESSION=1

注意 CLAUDE_CODE_CHILD_SESSION=1，说明这是一个子会话，环境变量是从父进程继承下来的。继续往上追：

grep -n "CLAUDE_CODE_SIMPLE" ~/.zshrc ~/.zprofile ~/.bashrc ~/.bash_profile ~/.profile ~/.zshenv 2>/dev/null

直接命中：

/Users/chenzc/.zshrc:47:export CLAUDE_CODE_SIMPLE=1

打开 .zshrc 第 45–47 行：

# claude code
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export CLAUDE_CODE_SIMPLE=1

根因实锤：.zshrc 里手动 export 了 CLAUDE_CODE_SIMPLE=1，每次开新 shell（包括 Claude Code 启动的子会话）都继承了它，于是 Claude Code 永远以 Minimal 模式运行。

---

四、修复方案

4.1 注释掉 .zshrc 里的开关

 # claude code
 export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
-export CLAUDE_CODE_SIMPLE=1
+# 关闭 SIMPLE 模式：否则会跳过 skill 目录发现、hooks、LSP、plugin sync 等
+# export CLAUDE_CODE_SIMPLE=1

4.2 让改动生效 + 清干净旧进程

这一步非常关键：变量已经在所有正在运行的 claude 进程的环境里，光改文件不够。

# 1. 让 .zshrc 改动在当前 shell 生效（或直接开新终端）
source ~/.zshrc

# 2. 确认变量已经清空（应该输出空行）
echo "$CLAUDE_CODE_SIMPLE"

# 3. 杀掉所有残留的 claude 进程（含 daemon / bg-spare / 子会话）
pkill -f "claude-code"

# 4. 重新启动
claude

4.3 验证修复

启动时打开 debug 日志：

claude --debug-file /tmp/claude-debug.log

另一个终端实时看：

grep "getSkills returning\|reduced mode" /tmp/claude-debug.log

修复前：

[reduced mode] Skipping skill dir discovery
getSkills returning: 0 skill dir commands, 0 plugin skills, 20 bundled skills, ...

修复后：reduced mode 那行消失，skill dir commands 变成非零数字（接近 ~/.claude/skills/ 下的实际目录数）。

---

五、经验总结

把这次排查中可复用的几条经验记一下：

5.1 「UI 数字 ≠ 实际加载」

/reload-skills 报「13 skills」是个误导。Claude Code 里类似的自定义 slash 命令，它的输出可能跟底层加载逻辑不一致。判定真实加载行为，永远以 --debug-file 日志里的 getSkills returning 行为准：

getSkills returning: {skill dir commands}, {plugin skills}, {bundled skills}, {builtin plugin skills}

四个数字相加才是真正可用的 skill 总数。

5.2 「reduced/minimal mode」是排雷高发区

CLAUDE_CODE_SIMPLE=1 一开，下面这些全部一起坏掉，而且症状分散，很难第一时间联想到是同一个根因：

• ❌ 用户级 / 项目级 skill 不被发现
• ❌ hooks 不执行
• ❌ LSP 不工作
• ❌ 插件不同步
• ❌ auto-memory 失效
• ❌ CLAUDE.md 不会被自动发现
• ❌ keychain 凭证不读取

所以如果遇到「好几个功能同时莫名其妙失效」，先 env | grep CLAUDE_CODE_SIMPLE 排查一下。

5.3 通用排查三步法

任何「资源/配置没生效」类问题：

1. 磁盘有没有  →  ls / stat
2. 进程看到没  →  debug log / verbose 模式
3. 谁阻断的   →  二进制 strings / 环境变量 / 配置文件

第 3 步在小工具上经常被忽略，但 strings <binary> | grep <关键字> 是非常高效的招数——很多「文档没写、但代码里写了」的隐藏行为都能这样挖出来。

5.4 改环境变量后必须重启进程

环境变量是在进程启动时一次性读入的。改完 .zshrc 后：

• source 只对当前 shell 生效
• 已经在跑的 claude 进程（特别是后台 daemon、bg-spare、child session）全部要杀掉重启，否则它们还在用旧环境

pkill -f claude-code 是最稳的做法。

---

六、附：关键命令速查

# 1. 看 skill 目录是否完好
ls ~/.claude/skills/ | wc -l
find ~/.claude/skills -maxdepth 2 -name SKILL.md | wc -l

# 2. 看进程实际加载了什么
claude --debug-file /tmp/cc.log
grep "getSkills returning\|reduced mode\|Skipping skill" /tmp/cc.log

# 3. 看 SIMPLE 模式开关来源
env | grep CLAUDE_CODE_SIMPLE
grep -rn "CLAUDE_CODE_SIMPLE" ~/.zshrc ~/.zprofile ~/.bashrc ~/.bash_profile ~/.profile ~/.zshenv 2>/dev/null

# 4. 看二进制里 reduced mode 的官方定义
strings $(readlink -f $(which claude)) | grep -iE "minimal mode|reduced mode|Skipping skill"

# 5. 修复后清干净进程
pkill -f claude-code && claude

---

写于 2026-07-06，基于 Claude Code 2.1.199 (build 968b0c41) 的实际排查。