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.
- License 许可
- MIT
- 最近更新
- 2026-10-25
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- id
- skill-issue
- name
- skill-issue
- risk
- safe
- tags
- [ "skills", "linter", "activation", "meta", "ci" ]
- tools
- [ "claude", "cursor", "gemini", "codex" ]
- author
- mishanefedov
- source
- community
- license
- MIT
- category
- meta
- date_added
- 2026-06-02
- 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.
- source_repo
- mishanefedov/skill-issue
- source_type
- community
- license_source
- https://github.com/mishanefedov/skill-issue/blob/main/LICENSE
03 SKILL.md 正文
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.
04 同仓库更多 Skills
zero-trust
Implement zero-trust network architecture. Configure identity-based access, micro-segmentation, and continuous verification. Use when implementing modern security architectures.
zcode-delegate
Delegate coding tasks to the Z.AI ZCode CLI only when the user explicitly requests it, while the orchestrator retains review and landing responsibility.
youtube-transcript
Fetch YouTube transcripts through DeepAPI or local fallback tooling and save clean text output.
youtube-transcript-skills
Fetch YouTube video transcripts, search videos/channels, browse channels, and extract playlists via the getyoutubetranscript.com API - free tier, no card required.
youtube-notetaker
Turn YouTube talks into local study notes with slides, transcripts, editable annotations, and a markdown-backed viewer.
youtube-full
Fetch YouTube transcripts, search videos, browse channels, and extract playlists via TranscriptAPI — no yt-dlp, no Google API key, works from any cloud server.