装完看不到技能

你会遇到什么

安装成功，但 /find-skills（或等价技能查看命令）看不到 brainstorming / systematic-debugging / test-driven-development 等技能。装完了却用不上。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

“安装成功”和“技能可见”之间隔着缓存这道桥：插件/技能包安装时先把内容解包落盘，客户端把扫描结果（技能清单）缓存起来供会话内查询——安装动作和扫描动作是两个时间点。装完立刻查，查的是旧缓存（还没重新扫描）；运行中的会话持有的是启动时的内存态，不会自动刷新。

这就是“装完看不见”的三个确定性格子：缓存未刷新（重开新会话触发重新扫描）、扫描目录不对（技能没落在 ~/.claude/skills/ 等固定路径，扫描根本看不到）、缓存不全（上游下载/解包中断导致技能数少了，如 Issue #818 的 7/14）。

验证顺序固定：先 /plugin list 确认插件本身可用（排掉插件层问题）→ 完全退出重开（强制重新扫描）→ 再 /find-skills。还有个提前量：tarball 解包后先数技能目录/SKILL.md/frontmatter，完整性在安装前就能确认。

一步步来

1. 确认插件状态 — 必做

/plugin list

感叹号 = 不可用（见症状 6 条目）。

2. 完全退出后重开新会话 — 必做

Ctrl+C 或 /exit 完全退出（不是开新窗口），重开再查。

3. 检查路径 — 排查

Claude Code 读 ~/.claude/skills/（或插件安装目录），不要放在其他目录：

ls ~/.claude/skills/

4. 缓存不全时重跑安装命令 — 必做

上游 Issue #818 场景：14 个技能只装了 7 个，重装补齐。

怎么确认修好了

技能完整可见（实测校验形态）：

tarball 结构：14 技能目录 / 14 SKILL.md / frontmatter 14/14 有效
新会话 /find-skills → brainstorming / systematic-debugging / test-driven-development 等出现

其它环境的表现

症状

安装成功，但 /find-skills（或等价技能查看命令）看不到 brainstorming / systematic-debugging / test-driven-development 等技能。

原因

技能缓存未刷新；未完全退出重开新会话；技能被放到 Claude 读不到的目录（路径放错）。

解法

1. /plugin list 确认插件状态（感叹号 = 不可用，见症状 6）。
2. 完全退出（Ctrl+C 或 /exit）后重开新会话再查。
3. 检查路径：Claude Code 读 ~/.claude/skills/（或插件安装目录），不要放在其他目录。
4. 缓存不全时重跑安装命令（上游 Issue #818 场景：14 个技能只装了 7 个，重装补齐）。