Skill issue

Skill sickn33/agentic-awesome-skills/skills/skill-issue

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.From its SKILL.md

Install

npx -y skills add sickn33/agentic-awesome-skills --skill skill-issue

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.0 KB, 595 tokens by cl100k_base, as published. Nobody here has run it

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                       # grade every skill A–F (+ collisions summary)
skill-issue ~/.codex/skills --why "deploy to prod" # which skill fires for this prompt, and why
skill-issue <dir> --collisions                     # clusters of skills that shadow each other
skill-issue <dir> --fix                            # append a "Use when …" clause to weak descriptions
skill-issue <dir> --json                           # machine-readable; exits non-zero on errors

Offline heuristic by default; add --llm to judge with a local claude/codex CLI.

Examples

Example 1: Audit installed skills

skill-issue ~/.claude/skills
# F  deploy-helper  ✗ no description — can never fire
# C  shipit         ! no "use when …" trigger clause
# A  rollback-prod  ✓ will fire on its triggers

Example 2: Diagnose a collision

skill-issue ~/.claude/skills --why "deploy the app to prod"
#  1. shipit       0.74  ← would fire
#  2. land-deploy  0.69  (margin 0.05 — ambiguous, likely collision)

Limitations

Offline scoring is heuristic and should be treated as a triage signal, not a final quality verdict.
Collision reports highlight likely shadowing, but agent-specific routers can weight metadata differently.
The --fix mode can improve weak trigger wording, but generated edits still need maintainer review before committing.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.