3 mishanefedov

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: A will fire on its triggers; F has 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.

配合站内内容