About

Imported from sickn33/agentic-awesome-skills (skills/skill-issue/SKILL.md). Install upstream with npx skills add sickn33/agentic-awesome-skills --skill skill-issue. Copyright stays with the author (MIT).

skill-issue — skill activation audit

Name: skill-issue
Author: sickn33

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.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/sickn33-agentic-awesome-skills-skill-issue/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

sickn33-agentic-awesome-skills-skill-issue.ocm.jsonjson

{
  "ocm": "1",
  "id": "sickn33-agentic-awesome-skills-skill-issue",
  "kind": "skill",
  "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.",
  "publisher": "sickn33",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "skills",
      "linter",
      "activation",
      "meta",
      "ci",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "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."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/sickn33/agentic-awesome-skills",
      "path": "skills/skill-issue/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/sickn33/agentic-awesome-skills/blob/HEAD/skills/skill-issue/SKILL.md",
      "key": "sickn33/agentic-awesome-skills/skills/skill-issue/SKILL.md"
    },
    "license": "MIT"
  },
  "instructions": "# skill-issue — skill activation audit\n\n## Overview\n\nA coding agent decides which skill to run from each skill's always-on `name` +\n`description`. A skill can be perfectly implemented and still never fire because\nits description is too vague to match how people phrase requests, or because a\nmore specific sibling silently wins. `skill-issue` audits exactly that surface,\ngrading each skill A–F, simulating which skill fires for a given prompt, and\nreporting collision clusters where one skill shadows another.\n\n## When to Use This Skill\n\n- Use when a skill you wrote never seems to trigger and you d",
  "cost": {
    "context_tokens": 613
  }
}

Fetch it by URL: GET /api/v1/registry/sickn33-agentic-awesome-skills-skill-issue/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.