OpenClaw Skill Not Triggered? Fix Installed Skills Fast

If your OpenClaw skill installs successfully but never triggers, do not start by reinstalling it.

"Installed" only means the skill files exist somewhere. "Triggered" means the active runtime can discover the skill, understand when to use it, prefer it over overlapping skills, and pass the first execution step without a policy block.

Use this page when you see searches or symptoms like OpenClaw skill not triggered, skill installed but not triggered, OpenClaw skill not working after install, or SKILL.md not selected.

If the exact error is permission denied, use the OpenClaw Skill Permission Denied Safe Fix Checklist. If the log says missing scope: operator.read, use the focused missing scope guide. For broad errors, use OpenClaw Skill Troubleshooting: 15 Common Errors.

TL;DR

• Confirm the skill is in the directory your active OpenClaw runtime actually scans.
• Confirm SKILL.md exists, is readable, and has a specific description.
• Test direct invocation before debugging auto-routing.
• Fix vague trigger wording with when to use, when not to use, examples, and output contract.
• Temporarily disable overlapping skills to isolate conflicts.
• Check logs to separate routing failure from permission or dependency failure.
• Validate with at least five prompt variations before calling the fix stable.

Table of contents

• Quick diagnosis: where the trigger broke
• Step 1: confirm the active skill path
• Step 2: check whether the runtime sees the skill
• Step 3: test direct invocation
• Step 4: rewrite weak SKILL.md trigger wording
• Step 5: isolate overlapping skills
• Step 6: check runtime policy and first-action failures
• Step 7: validate trigger stability
• SKILL.md trigger template
• FAQ
• References

Quick diagnosis: where the trigger broke

Start by classifying the failure. This prevents wasting time on the wrong fix.

A good rule: if direct invocation works but natural prompts fail, you likely have a routing problem, not an install problem.

Step 1: confirm the active skill path

A skill can be installed in one location while the running agent scans another. This is common when you mix project-level skills, global skills, and multiple agent runtimes.

Run read-only checks first. Adapt paths to your setup.

# Project-level skill folder example
ls -la ./skills/<skill-name>
test -f ./skills/<skill-name>/SKILL.md && echo "Project SKILL.md OK" || echo "Project SKILL.md MISSING"

# OpenClaw global skill folder example
ls -la ~/.openclaw/skills/<skill-name>
test -f ~/.openclaw/skills/<skill-name>/SKILL.md && echo "Global SKILL.md OK" || echo "Global SKILL.md MISSING"

What good looks like:

• The expected folder exists.
• SKILL.md exists and is readable.
• There are no duplicate folders such as my-skill, my_skill, and my-skill-main.
• The skill is installed under the same target your current OpenClaw session uses.

If you installed with npx skills add, also check the skills CLI list output:

npx skills list
npx skills list -g

If the skill appears globally but the active workspace only scans project skills, reinstall into the correct scope instead of editing the skill content.

Step 2: check whether the runtime sees the skill

After file-path checks, verify runtime discovery.

Use your OpenClaw UI, skill list, or runtime diagnostics to answer:

• Is the skill visible to the active workspace?
• Is it enabled?
• Does it show the expected name and description?
• Does the runtime show any load error for SKILL.md?
• Did you reload the runtime after installation?

If the UI or runtime list does not show the skill, fix discovery first. Trigger wording cannot help a skill the runtime has not loaded.

Step 3: test direct invocation

Direct invocation separates routing confidence from execution readiness.

Use a prompt like this:

Use <skill-name> for this task. First explain why this skill matches. Then run one harmless, non-destructive first step only.

Interpret the result:

Do not test with a risky production task. Use a harmless prompt that does not write files, run deployment commands, or call external services.

Step 4: rewrite weak SKILL.md trigger wording

Most "installed but not triggered" problems come from vague descriptions.

A weak skill description says:

Helps with coding tasks.

A stronger description says:

Use this skill when the user asks to debug why an OpenClaw skill is installed but not triggered, including SKILL.md path checks, trigger wording, overlap isolation, runtime policy checks, and dry-run validation.

The stronger version gives the router concrete intent, task type, and boundaries.

What to add to SKILL.md

Add or improve these blocks:

Bad vs better trigger wording

Specific wording improves both human understanding and agent routing.

Step 5: isolate overlapping skills

If two skills claim the same job, routing may pick the wrong one.

Use this isolation sequence:

1. List skills that could match the same prompt.
2. Temporarily disable the nearest overlapping skill.
3. Run the exact same prompt again.
4. Re-enable one skill at a time.
5. Add when not to use boundaries to both conflicting skills.

Example conflict:

Internal links can help users choose the right guide too. For example, permission-denied symptoms should point to the OpenClaw Skill Permission Denied Safe Fix Checklist, while broad failures should point to the 15 common error guide.

Step 6: check runtime policy and first-action failures

Sometimes a skill is triggered, but the first action is blocked. To the user, it looks like the skill was never used.

Check logs for:

• Permission denied.
• Missing dependency or command not found.
• Missing environment variable.
• Blocked shell command.
• Blocked file path.
• Blocked network host.
• missing scope: operator.read or similar scope errors.

Use the right follow-up page:

Do not rewrite trigger language until logs prove the skill was not selected. If it was selected and then blocked, fix execution policy instead.

Step 7: validate trigger stability

One successful run is not enough.

Use this five-prompt stability test:

Track each run:

Prompt:
Expected skill:
Actual skill:
First action:
Pass/fail:
Notes:

A stable fix should pass at least four of five tests and should not require broad permission changes.

SKILL.md trigger template

Use this template when improving a skill that installs correctly but does not trigger reliably.

---
name: <skill-name>
description: Use this skill when <specific user intent>, especially when <task context>. Do not use it for <nearby but different task>.
---

# <Skill Name>

## When to use

- <specific trigger intent 1>
- <specific trigger intent 2>
- <specific trigger intent 3>

## When not to use

- <boundary 1>
- <boundary 2>

## Inputs needed

- Skill name or page path
- Error text or user request
- Environment or runtime context

## First safe action

Start with read-only inspection. Do not edit files, run destructive commands, or expand permissions until the failure layer is classified.

## Workflow

1. Confirm install path and SKILL.md visibility.
2. Test direct invocation.
3. Check trigger wording.
4. Isolate overlapping skills.
5. Check logs for execution blocks.
6. Validate with five prompt variations.

## Output contract

Return:

- likely root cause
- evidence
- exact fix
- validation prompts
- rollback note

FAQ

Why is my OpenClaw skill installed but not triggered?

Usually because the active runtime cannot see the skill, the trigger description is too vague, another skill overlaps with the same intent, or the first action is blocked by policy and looks like a trigger failure.

What should I check first?

Check whether SKILL.md exists in the active skill path and whether the runtime lists the skill. If the runtime cannot see it, do not edit the trigger wording yet.

How do I test whether routing is the problem?

Use a direct prompt that names the skill. If direct invocation works but natural prompts fail, the likely problem is weak trigger language or overlap.

Can overlapping skills stop triggering?

Yes. If two skills cover the same intent without clear boundaries, routing can select the wrong skill. Add when not to use boundaries and test with overlapping prompts.

Is this the same as permission denied?

No. Permission denied is an execution-layer problem. A not-triggered issue is usually discovery or routing. Logs decide which one you have.

How do I know the fix is stable?

Run at least five prompt variations and confirm the correct skill is selected consistently. Record the prompts and results in your team notes.

References

• Vercel Labs skills CLI repository
• Google Developers: Writing clear documentation
• Playwright Docs: Debugging tests
• Node.js Docs: Environment variables and process behavior
• OWASP: Logging Cheat Sheet
• Google SRE Workbook: Monitoring Distributed Systems

Related:

• How to Install OpenClaw Skills
• OpenClaw Skill Permission Denied: Safe Fix Checklist
• Fix missing scope: operator.read in OpenClaw
• How to Fix Missing Dependency in OpenClaw Skills
• OpenClaw Skill Troubleshooting: 15 Common Errors
• OpenClaw Skill Security Checklist