nicholyx/ai-skills / custom/daily/skills-doctor
skills-doctor
Verified诊断「技能装了却没反应」—— 检查技能装在哪个目录、软链有没有断、SKILL.md 能不能被加载、有没有被别的目录顶掉。当用户说「技能装了但用不了,帮我看看」「技能没反应」「我说了触发词什么都不发生」「检查一下技能装好没有」「skills 怎么不生效」时使用。
技能装好了却没反应?按这四步查
什么时候用
- 「我装了技能,但怎么说都不触发」
- 「之前能用,现在没反应了」
- 「换台机器/换个目录就不好使了」
- 「帮我看看技能到底装上没有」
只管诊断,不做修改 —— 找到原因后把修复命令给用户,让他自己决定要不要执行。 删软链、改配置这类动作,未经明确同意不要做。
一条前提
「装了」和「能被加载」是两件事。 技能文件躺在磁盘上不代表工具看得见它: 可能装错了位置、软链断了、目录被别的工具顶掉、或者 frontmatter 坏了导致静默跳过。 这个技能就是把这三件事分开查。
第一步:它到底装在哪
npx skills 装到两个位置之一,很多人是在一个目录装的、在另一个目录用:
for d in ./.agents/skills ./.claude/skills ~/.agents/skills ~/.claude/skills; do
if [ -d "$d" ]; then
printf '%s → %s 项\n' "$d" "$(ls -1 "$d" 2>/dev/null | wc -l | tr -d ' ')"
else
printf '%s → 不存在\n' "$d"
fi
done
- 项目级(
./.agents/skills+./.claude/skills)是默认落点,只在这个项目里生效 - 用户级(
~/.agents/skills+~/.claude/skills)要-g或--global,全局生效
最常见的误判:在 A 目录装的,在 B 目录里找。先把这条排除掉。
第二步:软链有没有断
.claude/skills/ 里通常是指向 .agents/skills/ 的软链。目标被移动或删除后,
链接还在、但指向空气 —— 技能就这么静默消失了,没有任何报错。
find ./.claude/skills ~/.claude/skills -maxdepth 1 -type l 2>/dev/null | while read -r f; do
[ -e "$f" ] || printf '断链:%s → %s(目标不存在)\n' "$f" "$(readlink "$f")"
done
有输出就是找到了 —— 把每一个断链的条目名原样报给用户。
别用
for f in .claude/skills/*。 目录不存在时,zsh 会报no matches found并中断整条命令(macOS 默认就是 zsh),于是你会以为「没查到」, 其实是命令根本没跑完。find对不存在的目录只是往 stderr 抱怨一句,不影响其余部分。
第三步:SKILL.md 能不能被加载
对第一步里每个存在技能的目录,逐个检查。加载失败通常是静默的,所以只能自己验:
find ./.agents/skills ./.claude/skills ~/.agents/skills ~/.claude/skills \
-maxdepth 1 -mindepth 1 2>/dev/null | while read -r d; do
[ -d "$d" ] || continue # 跟随软链;断链在第二步已单独报
name=$(basename "$d")
f="$d/SKILL.md"
if [ ! -f "$f" ]; then
printf '缺 SKILL.md:%s\n' "$d"
continue
fi
if ! head -1 "$f" | grep -qx -- '---'; then
printf '没有 frontmatter:%s\n' "$f"
continue
fi
fm_name=$(sed -n 's/^name:[[:space:]]*//p' "$f" | head -1)
if [ -z "$fm_name" ]; then
printf '缺 name 字段:%s\n' "$f"
elif [ "$fm_name" != "$name" ]; then
printf 'name 与目录名不符:%s(目录 %s,name %s)\n' "$f" "$name" "$fm_name"
fi
done
三类问题都不会报错,只会让技能用不了:缺 SKILL.md、没有 frontmatter、
name 与目录名不一致。
第四步:有没有被别的目录顶掉
同一个技能名出现在多个目录时,谁生效取决于工具的查找顺序 —— 而这种覆盖是静默的。
find ./.agents/skills ./.claude/skills ~/.agents/skills ~/.claude/skills \
-maxdepth 1 -mindepth 1 2>/dev/null | while read -r p; do
[ -d "$p" ] || continue
printf '%s\t%s\n' "$(basename "$p")" "$(cd "$p" && pwd -P)"
done | sort -u | cut -f1 | uniq -d
有输出说明这些名字装了不止一份。重点看:两份内容是否一致、其中一份是不是很久 没更新的旧版本。
必须按解析后的真实路径去重(
pwd -P)。.claude/skills/<名字>通常就是指向.agents/skills/<名字>的软链 —— 同一份东西。只比名字的话,每一个技能都会被 报成重名,真正的问题反而淹在里面。
这个仓库自己踩过一次:项目里多了一个
.claude/skills/(另一个工具写进去的 9 个 技能),把本该生效的那批整个顶掉 —— 装的人以为装的是 A,实际生效的是 B。
报告怎么写
先给结论,再给证据。 格式:
## 结论
<能用 / 不能用 / 部分不能用>,原因:<一句话>
## 查到什么
| 位置 | 项数 | 问题 |
| --- | --- | --- |
| ./.agents/skills | 15 | — |
| ./.claude/skills | 15 | 2 个断链 |
| ~/.claude/skills | 8 | — |
## 有问题的条目
- 断链:`./.claude/skills/xxx` → `../../.agents/skills/nonexistent`(目标不存在)
- name 与目录名不符:`./.agents/skills/foo/SKILL.md`(目录 foo,name bar)
## 建议怎么修
<具体命令,一条一条列>
要求:
- 问题条目一律原样引用路径与名字 —— 用户要拿它去搜、去删,改写了就没用
- 没查到问题就直说没查到,不要为了显得有用而凑几条模糊的「建议优化」
- 每一步的实际输出要能对上 —— 报「15 项」就该真数出 15 项
边界
- 只诊断,不改。 修复命令给出来,让用户自己执行;删软链、动配置尤其要问
- 不猜。 查不到原因就说「按这四步没发现异常,可能是工具版本或它自己的配置问题」, 并建议下一步查哪里 —— 不要编一个像模像样的原因
- 不评价技能内容好不好用。 这里只回答「它能不能被加载」
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |