装完看不到技能 / document-skills 安装问答

你会遇到什么

按教程装完（/plugin install 流程或方式 B），在 agent 里看不到技能；或 document-skills 子集安装后没效果。装了半天，白装了。

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

为什么会这样

技能包本质是目录复制（无二进制），"装完看不见"基本就三个原因：

document-skills 属同一技能集子集，问题同源（网络/权限/版本不兼容是常见失败面，CSDN 安装问答）。

技能包是“目录即能力”：agent 的技能发现机制是启动时扫描固定目录（~/.claude/skills/ 下每个含 SKILL.md 的子目录算一个技能），不是运行时实时刷新——这是“装完看不见”的根因所在。整个链路是：复制目录（写盘）→ agent 启动扫描（读盘）→ 技能列表呈现（运行时内存态）。

三层任何一层断都表现为“看不见”：目录复制到别处 = 扫描目录里根本没有；没重启 = 内存态还是旧的；权限/半成品目录 = 扫描时读失败被跳过。所以排查顺序固定：先 ls 核对目标目录（确认写盘层），再完全退出重启（刷新内存态），最后才怀疑权限/版本——顺序反了会误判“白装了”。

一步步来

1. 核对技能目录 — 必做

ls ~/.claude/skills/agent-skills

应 24 目录，每个含 SKILL.md（实测复制后形态）。

2. 完全退出并重启 agent 会话 — 必做

技能在启动时扫描，运行中不会刷新——完全退出（不是开新窗口）再启动。

3. 权限与版本核对 — 必做

ls -ld ~/.claude/skills/agent-skills && cat ~ | head -1

确认目标目录可写；确认 tag 与收录版本（0.6.7）一致。

怎么确认修好了

目录结构与重启后可见（实测形态）：

ls ~/.claude/skills/agent-skills
→ 24 个子目录 + 24 个 SKILL.md

重启 agent 后技能列表里能看到对应技能；document-skills 子集同样生效。

其它环境的表现

症状

按教程装完（/plugin install 流程或方式 B），在 agent 里看不到技能；或 document-skills 子集安装后无效果。

原因

技能包本质是目录复制（无二进制）：装错目录、未完全退出重启 agent、或复制时权限/路径不对都会「装完看不见」；document-skills 属同一技能集子集，问题同源（网络/权限/版本不兼容是常见失败面，CSDN 安装问答）。

解法

1. 核对技能目录：ls ~/.claude/skills/agent-skills（应 24 目录，每个含 SKILL.md）。
2. 完全退出并重启 agent 会话再试（技能在启动时扫描）。
3. 权限问题：确认目标目录可写；版本问题：确认 tag 与收录版本（0.6.7）一致。

未能实测项（如实标注）

• 真实 Claude Code/Cursor/Codex 环境加载 24 技能（需对应 IDE/账号）；document-skills 子集单独安装；--list 浏览模式；全部 24 技能逐项验证；Windows/macOS 环境。