skill-issue
Helps understand why a coding function isn't working. It checks and grades functions to find issues and conflicts.
What it does
This tool helps understand why a programming function (called a 'skill') isn't working as expected. It checks if the function's description is clear enough to be found and if it's not being 'hidden' by a similar function.
When to use it
- ✓When a function you created isn't being activated.
- ✓When you want to know which function will be used for a specific request.
- ✓To check if new functions work well before adding them.
Example of what to ask your AI
“Audit my programming functions in the directory '~/my_agents'”
Want more? Open the sections below.
How to use
The easiest way: copy the message below and paste it into Claude, ChatGPT, Cursor or any AI. It reads the skill and follows the instructions.
Skill link
Ready-to-paste message
How it works
The tool analyzes each function's description and compares it to how people phrase requests. It gives each function a grade (A-F) and warns if one function is preventing another from working.
Installation
Easiest way: copy the skill link and paste it into Claude, ChatGPT or Cursor asking it to follow the instructions.
In the terminal (Claude Code, Codex, Cursor), in your project folder:
npx skills add sickn33/agentic-awesome-skills --skill skill-issueOr download just the file:
curl -L https://raw.githubusercontent.com/sickn33/agentic-awesome-skills/main/skills/skill-issue/SKILL.md -o SKILL.mdTechnical content (original SKILL.md)
Original text by the author, straight from GitHub.
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
--fixmode can improve weak trigger wording, but generated edits still need maintainer review before committing.
FAQ
What does the A-F grade mean?
The grade indicates the likelihood of the function being found and activated. 'A' is excellent, 'F' means it will likely never be activated.
What is a 'collision'?
A collision occurs when two functions have very similar descriptions, and one ends up 'hiding' the other, preventing the second one from being used.
Does the tool use artificial intelligence?
Yes, it can use a local artificial intelligence to analyze requests, but it also works with a simpler analysis without needing it.
Details
Original description by the author
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.
Popularity
- GitHub stars
- 48k
- Ranking position
- #4683
- License
- MIT
- Updated
- 10/15/2026
Comments
- …
More skills from this repository
00-andruia-consultant
Helps your agent start or improve AI projects. It analyzes code, suggests tools, and creates action plans in Spanish.
sickn33/agentic-awesome-skills
007
Lets your agent perform security audits and threat modeling. It's useful for protecting projects against attacks and vulnerabilities.
sickn33/agentic-awesome-skills
10-andruia-skill-smith
Helps your agent create or improve AI tools. It defines how tools work, writes documentation, and validates the structure.
sickn33/agentic-awesome-skills
20-andruia-niche-intelligence
Lets your agent create a summary about a specific industry. It's useful for understanding the context, rules, usage patterns, and risks of a project, using reliable sources.
sickn33/agentic-awesome-skills
Similar skills
cpp-testing
Makes your agent write and improve tests for C++ code. It helps set up testing tools and fix errors.
affaan-m/ECC
csharp-testing
Helps your agent create tests for C# and .NET code. It uses best practices to ensure tests are efficient and reliable.
affaan-m/ECC
django-tdd
Enables your agent to apply testing strategies for Django with pytest-django and TDD. It's useful for writing robust tests and ensuring code quality, especially for DRF APIs.
affaan-m/ECC