| id | skill-issue |
| name | skill-issue |
| description | Find out why a coding-agent skill won't fire — grade each SKILL.md A–F on activation, simulate which skill a prompt triggers, and flag collisions where one silently shadows another. |
| category | meta |
| risk | safe |
| source | community |
| source_repo | mishanefedov/skill-issue |
| source_type | community |
| date_added | 2026-06-02 |
| author | mishanefedov |
| tags | ["skills","linter","activation","meta","ci"] |
| tools | ["claude","cursor","gemini","codex"] |
| license | MIT |
| license_source | https://github.com/mishanefedov/skill-issue/blob/main/LICENSE |
skill-issue — skill activation audit
Overview
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 a
more specific sibling silently wins. skill-issue audits exactly that surface,
grading each skill A–F, simulating which skill fires for a given prompt, and
reporting collision clusters where one skill shadows another.
When to Use This Skill
- Use when a skill you wrote never seems to trigger and you don't know why
- Use when the user says "why isn't my skill firing", "which skill fires for X", or "audit my skills"
- Use after writing or installing a new SKILL.md, to confirm it will actually be picked
- Use in CI to fail a PR that adds a skill with empty/duplicate/colliding metadata
How It Works
Install the CLI (npm i -g @misha_misha/skill-issue, brew install mishanefedov/skill-issue/skill-issue, or npx @misha_misha/skill-issue), then:
skill-issue ~/.claude/skills
skill-issue ~/.codex/skills --why "deploy to prod"
skill-issue <dir> --collisions
skill-issue <dir> --fix
skill-issue <dir> --json
Offline heuristic by default; add --llm to judge with a local claude/codex CLI.
Examples
Example 1: Audit installed skills
skill-issue ~/.claude/skills
Example 2: Diagnose a collision
skill-issue ~/.claude/skills --why
