How do I install the Skill Issue skill?

Run npx skillmds@latest add mishanefedov/skill-issue in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Skill Issue safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Skill Issue?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Skill Issue free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Skill Issue?

mishanefedov (@mishanefedov) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Skill Issue by mishanefedov — Agent Skill

Name: Skill Issue
Rating: 4.2 (5 reviews)
Author: mishanefedov

File contents

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.

---name: skill-issuedescription: 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.license: MIT---# skill-issue — skill activation audit## OverviewA 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 becauseits description is too vague to match how people phrase requests, or because amore specific sibling silently wins. `skill-issue` audits exactly that surface,grading each skill A–F, simulating which skill fires for a given prompt, andreporting 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 WorksInstall the CLI (`npm i -g @misha_misha/skill-issue`, `brew install mishanefedov/skill-issue/skill-issue`, or `npx @misha_misha/skill-issue`), then:```bashskill-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 whyskill-issue <dir> --collisions # clusters of skills that shadow each otherskill-issue <dir> --fix # append a "Use when …" clause to weak descriptionsskill-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```bashskill-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```bashskill-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.

Frequently asked questions

Skill Issue