skill-issue Skill
排查 coding-agent 技能为何不触发。审计已安装技能的激活元数据:对每条描述能否被可靠识别进行 A–F 评级,模拟给定提示词会触发哪个技能,并报告两个技能冲突导致其中一个静默失效的情况。当用户说"我的技能为什么不触发"、"skill-issue"、"哪个技能会触发"、"审计我的技能"、"我的技能从未触发"、"技能冲突",或在编写或安装新的 SKILL.md 后使用。
安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。
技能指令原文(SKILL.md)
skill-issue — skill activation audit
A coding agent decides which skill to run from each skill's always-on name +
description. A skill can be perfectly implemented and still never fire because
its description is too vague to match how people phrase requests, or because it
collides with a more specific sibling. skill-issue audits exactly that surface.
Run it
When installed as a plugin, skill-issue is already on PATH:
skill-issue ~/.claude/skills # grade every skill A–F (+ collisions summary)
skill-issue ~/.claude/skills --why "deploy to prod" # which skill fires for this prompt, and why
skill-issue ~/.claude/skills --collisions # clusters of skills that shadow each other
skill-issue ~/.claude/skills --fix # add a "Use when …" clause to weak descriptions
skill-issue . # audit the current repo's skills/ + agents/
skill-issue ~/.claude/skills --json # machine-readable
Add --skill to --why to focus on one skill and see which of the
prompt's words its description is missing. Add --llm to judge with a local
claude/codex CLI instead of the offline heuristic.
Interpreting output
- lint grades:
Awill fire on its triggers;Fhas an error (empty or
duplicated description) and can never be told apart. B–D are graded warnings
(no "use when" clause, too vague, too thin/heavy, restates the name).
- --why: skills ranked by how much of the prompt's salient, rarity-weighted
vocabulary each covers. ← would fire marks the winner; a small margin to #2
means an ambiguous collision; "no skill reliably fires" means the best match is
too weak (its description is missing the prompt's words).
- --collisions: each cluster lists the skills that share trigger vocabulary;
one silently wins the shared intent and the rest never fire.
Exit code is 1 when any skill has an error-level defect, so it can gate a commit
hook.
Scope (v1)
Heuristic, offline, conservative: only empty/duplicated descriptions are errors;
everything else is a graded warning. It does NOT yet run the real agent loop to
observe selection (the v2 replay roadmap) — it predicts from the metadata the
picker reads. If skill-issue: command not found, run npx @misha_misha/skill-issue
or install with
npm i -g @misha_misha/skill-issue.