Your Claude Code or Codex skill isn't triggering. Here's how to find out why.

Updated 2026-10-27 · based on real claude -p / codex exec runs, not simulations.

Short answer

Most "my skill doesn't fire" cases are not a broken skill. Either another installed skill wins the request, or the description has wording that makes the model treat it as manual-only. Isolated evals (one skill in a clean environment) can't see either problem. In one measured setup, prompts that fired 21/21 in an isolated eval missed 5 times with the user's other skills installed.

Step 1: rule out discovery problems (no model calls)

Frontmatter must start the file: ---, name:, description:, ---. A YAML error silently hides the skill.
name should equal the folder name, lowercase with hyphens.
Claude Code: check skillOverrides in settings.json, and disable-model-invocation: true.
Codex: a nested SKILL.md in a subfolder is registered as a separate skill.

python3 skillcheck.py scan

Step 2: measure real triggering with all your skills loaded

python3 skillcheck.py gen --skills my-skill --out suite.json   # should-fire + near-miss prompts
python3 skillcheck.py run --agent claude --suite suite.json --tag before --runs 3
python3 skillcheck.py report --tag before

The report's taken by column shows which other skill loaded instead. Repeat each prompt (--runs 3): triggering is not fully deterministic, and an untouched skill was seen moving between 2/3 and 1/3.

Step 3: fix the description, then prove it

Symptom	Fix	Measured
Never fires from plain requests; nothing else takes it	Remove slash-only wording ("use as /name <topic>")	0/4 → 4/4
Misses natural phrasings	Quote the user's literal phrasings, including questions ("can I conclude …?")	1/4 → 4/4
Another skill takes it	State the boundary in both descriptions	2/3 → 3/3
Fires on near-misses	Add one "Not for …" sentence naming the neighbours	—

python3 skillcheck.py run --agent claude --suite suite.json --tag after --runs 3
python3 skillcheck.py compare --before before --after after

Re-test with prompts written before the edit, so the fix isn't fitted to the test.

Get the tool

/plugin install skillcheck --marketplace Noem836/skillcheck

Or the single file: github.com/Noem836/skillcheck (MIT, Python stdlib). AI agents can also call the hosted static checker over MCP at https://skillcheck-d1d57e.fly.dev/mcp (tools preflight_skill before installing a skill, check_skill_repo before publishing).