Why does a skill install but never trigger?

The most common causes are weak skill scope wording, overlap with similar skills, or runtime policy restrictions that suppress execution confidence.

What should I test first?

First confirm canonical SKILL.md path and run a direct invocation prompt with explicit task fit and non-destructive action requirements.

How do I reduce trigger conflicts?

Temporarily disable overlapping skills, tighten trigger language, and define clear when-to-use and when-not-to-use boundaries.

Skill Installed but Not Triggered? Full Fix Checklist

A successful install only proves files exist. It does not prove routing confidence.

If your OpenClaw skill is installed but never selected, you need to debug four layers in order:

canonical install integrity
routing and scope clarity
overlap/conflict with nearby skills
runtime permissions and execution policy

This guide gives a reproducible sequence that helps teams avoid guesswork and false fixes.

TL;DR

"Installed" and "triggered" are different states.
Most trigger failures come from vague scope or overlap, not missing files.
Use a fixed triage order: file path -> scope wording -> overlap isolation -> policy checks.
Lock the fix with repeated prompts and documented trigger cues before re-enabling full skill sets.

Understand the failure mode first
Step 1: confirm canonical install path
Step 2: validate scope and trigger language
Step 3: run direct invocation diagnostics
Step 4: isolate overlap conflicts
Step 5: verify runtime permissions and policies
Step 6: validate fix stability
Symptom-to-cause table
Operational checklist for teams
Conclusion
FAQ
References

Understand the failure mode first

Before changing anything, classify what you actually observe.

Case A: Skill not visible in registry -> install/path problem.
Case B: Skill visible but never selected -> routing/scope problem.
Case C: Skill selected then silently fails -> runtime policy/dependency problem.

Many teams confuse Case B and Case C. That leads to wasted edits in SKILL.md when the real blocker is execution policy.

Step 1: confirm canonical install path

Start with integrity checks.

test -f ~/.agents/skills/<skill-name>/SKILL.md
ls -la ~/.agents/skills | rg "<skill-name>"

What good looks like:

exact skill directory exists
SKILL.md present and readable
no duplicated skill folders with similar names

If multiple similar folders exist, remove ambiguity first. Duplicate definitions often create inconsistent routing behavior.

Step 2: validate scope and trigger language

Routing confidence depends heavily on scope clarity.

A weak description like "helps with coding" is too broad. It competes with many skills and loses routing confidence.

Better scope template

When to use: explicit user intents
When not to use: boundaries against nearby skills
Trigger phrases: natural phrases users actually type
Output contract: expected result format

Example pattern

Bad:

"Useful for testing web apps"

Better:

"Use this skill when the task requires browser-based validation of local web flows, screenshots, or smoke checks before release."

Boundary:

"Do not use for backend unit tests or static code linting tasks."

Step 3: run direct invocation diagnostics

Use a controlled prompt to separate install issues from routing confidence issues.

Prompt pattern:

Use <skill-name> for this task. Explain why the skill matches, then run one non-destructive first step.

Interpretation:

if this works, install is fine and auto-routing confidence is the issue
if this fails, inspect runtime policy and dependency logs

Run at least three variants of the same prompt with slightly different phrasing. Unstable selection usually indicates borderline scope wording.

Step 4: isolate overlap conflicts

If multiple skills claim similar territory, routing may choose a different skill.

Isolation method:

disable adjacent/overlapping skills temporarily
run the same diagnostic prompt
re-enable one overlapping skill at a time
identify conflict pair

Once conflict pair is known, update both descriptions with explicit boundaries.

Practical boundary rules

define a primary object (for example "browser interactions" vs "React refactor")
define disallowed scenarios
avoid one-line generic descriptions

Step 5: verify runtime permissions and policies

A skill can appear "not triggered" when it was selected but blocked at execution.

Check for:

permission denied for required tools
blocked command prefixes
missing API credentials
sandbox write restrictions

If policy blocks first action, users may perceive the skill as "not used." In logs, this usually appears as early command rejection.

Step 6: validate fix stability

Do not stop after one successful run.

Use a stability gate:

run 3-5 prompt variations
confirm consistent skill selection
verify first executable step passes policy checks
document trigger phrases and boundaries in team notes

Only then re-enable full skill stack.

Symptom-to-cause table

Symptom	Likely cause	First action
Skill missing from list	wrong install path or missing SKILL.md	verify canonical file path
Skill listed but never selected	vague scope or overlap	tighten description and isolate conflicts
Skill selected but no useful action	output contract unclear	add deterministic workflow and expected output
Skill starts then aborts	policy/dependency block	inspect permission and command policies
Works in one prompt but not another	fragile trigger language	add explicit trigger phrases and boundaries

Operational checklist for teams

Use this as a release-safe SOP.

Pre-fix

capture exact failing prompt
capture current skill description
capture enabled overlapping skills

During fix

change one variable at a time
keep prompts fixed while testing
log each pass/fail result

Post-fix

run repeated prompt validation
update team runbook with trigger cues
schedule periodic review when new skills are added

Conclusion

For "skill installed but not triggered" issues, random trial-and-error is slow and unreliable.

Use a deterministic sequence:

verify path integrity
improve scope wording
isolate overlap
validate runtime policy
lock fix with repeated tests

This approach reduces false positives, improves routing stability, and keeps your skill ecosystem maintainable as it grows.

FAQ

Is reinstalling always necessary?

No. Reinstall helps only for integrity/path issues. Most trigger problems are scope and routing issues.

How many overlapping skills are too many?

There is no fixed number, but overlap without clear boundaries quickly degrades routing confidence.

Should we disable auto-routing entirely?

Usually no. Keep auto-routing, but strengthen descriptions and boundaries. Disable only while doing focused diagnostics.