OpenClaw Skill Troubleshooting Guide: Fix Routing, Config, and Runtime Failures

When an OpenClaw skill works once and then quietly stops showing up, I do not start by rewriting the skill. I run a small operator checklist: prove the file exists, prove the trigger description is specific, prove the tool calls are allowed, and prove the failure is not coming from stale memory or missing credentials. This guide is the exact troubleshooting path I use when a custom skill is supposed to automate real work and the agent keeps ignoring it, misrouting it, or failing halfway through.

The goal is not a prettier skill folder. The goal is a skill that survives daily use. If you are still designing your first skill, start with the foundation in the custom OpenClaw skills developer guide, then come back here when the skill needs to behave predictably under pressure.

Setup: Build a Reproducible Skill Diagnostic Pass

I want every troubleshooting session to begin with evidence. OpenClaw skills are simple on purpose: a directory, a SKILL.md file, a useful description, and supporting scripts or docs when needed. Most failures happen because one of those pieces is missing, ambiguous, or living in the wrong place.

Run this from the Mac or server where OpenClaw is actually running. Do not inspect a cloned repo and assume the runtime can see it.

pwd openclaw skills check find ~/.openclaw/skills -maxdepth 3 -name SKILL.md -print | sort find ~/.openclaw/workspace/skills -maxdepth 3 -name SKILL.md -print | sort

I use the two find commands because personal skills and workspace skills often coexist. If a skill exists in your editor but not under one of those paths, OpenClaw will not reliably load it. If the same skill name appears twice, remove the duplicate or rename one of them. Duplicate skill names create routing confusion that looks like model inconsistency but is really file-system ambiguity.

Next, inspect the first screen of the skill file. The name and description should tell the model when to use it, not just what it is called.

sed -n '1,80p' ~/.openclaw/skills/my-skill/SKILL.md

A weak description says, “helps with APIs.” A useful description says, “Use this when the user asks to fetch, normalize, or publish product data from the Shopify Admin API.” The second version gives the router a clear match. It also prevents the skill from being invoked for unrelated API work.

If you are building a whole skill system rather than fixing one file, pair this with the OpenClaw skills guide. The guide explains the model; this article is the field checklist.

Configuration: Check Names, Paths, Permissions, and Secrets

Once the skill exists, I check configuration in four layers: name, path, permissions, and secrets. That order matters. There is no value debugging OAuth when the skill file is not loadable.

First, verify that the skill directory name is boring. Use lowercase letters and dashes. Avoid spaces, emoji, dates, and clever internal project names. The skill name should look like the thing a user would ask for.

ls -la ~/.openclaw/skills ls -la ~/.openclaw/workspace/skills

Second, verify that helper scripts can execute. A common failure is a great skill document that points to a shell script with no execute bit. OpenClaw can read the instructions, but the command fails when the skill tries to act.

ls -la ~/.openclaw/skills/my-skill chmod 755 ~/.openclaw/skills/my-skill/run.sh bash ~/.openclaw/skills/my-skill/run.sh --help

Third, check the runtime environment. If the skill expects a credential, do not paste the secret into the skill file. Store it in the configured secret path or environment layer for your system, then have the skill reference the command that reads it. The skill should describe the dependency, not contain the private value.

env | grep OPENCLAW which node which python3 python3 --version node --version

Fourth, verify that any external dependency is installed in the same environment used by OpenClaw. I see this with Python constantly: a package exists in one virtual environment, while the agent executes another interpreter.

python3 -m pip show requests python3 -m pip show google-api-python-client npm list --depth 0

If a command fails here, fix the environment before touching the skill instructions. A vague skill can still sometimes work. A missing binary cannot.

Usage: Force a Clean, Observable Test Run

After setup and configuration pass, I test the skill with the smallest real request that should trigger it. The request should include the object, the action, and the expected output. “Use my research skill” is too vague. “Use the web research skill to collect five source URLs and summarize the installation steps for Browserbase” is testable.

I keep a scratch note for the run. You can use any file, but I like a timestamped log because it gives me something to compare across retries.

mkdir -p ~/.openclaw/workspace/tmp DATESTAMP=$(date +%Y-%m-%d-%H%M) touch ~/.openclaw/workspace/tmp/skill-test-$DATESTAMP.md

Then I run the helper script directly if the skill has one. Direct execution separates tool failure from routing failure. If the script fails from the terminal, the skill will fail from the agent too.

cd ~/.openclaw/skills/my-skill bash run.sh --sample bash run.sh --verbose

If direct execution works, test the actual agent flow with a specific prompt. Ask for one deliverable, not a bundle. Skills fail more often from overloaded prompts than from bad code.

Good test prompt: “Use the GitHub issues skill to list the five newest open issues in owner repo and group them by label.” Bad test prompt: “Audit GitHub, make a roadmap, fix anything obvious, and post an update.” The second prompt mixes research, planning, coding, and messaging. A skill can be part of that workflow, but it should not be expected to own all of it.

When the output is wrong, classify the failure before changing anything. I use three buckets:

• Not selected: the skill never loaded or the description did not match the request.
• Selected but failed: the instructions routed correctly, but a command, credential, or API failed.
• Selected and drifted: the skill started correctly, then ignored constraints or invented missing data.

Each bucket has a different fix. Routing failures need clearer descriptions. Execution failures need command and credential repair. Drift needs stricter “do not” rules, smaller steps, or deterministic helper scripts.

Advanced Tips: Make Skills Deterministic Where It Matters

The best OpenClaw skills do not ask the model to improvise everything. They use the model for judgment and orchestration, then push brittle work into deterministic scripts. If a workflow has parsing, publishing, schema validation, or repeated API writes, put that logic in code and have the skill call it.

For example, a content publishing skill should not hand-write a large page component when a renderer can wrap trusted metadata and body content. A GitHub triage skill should not freehand pagination logic when a script can fetch issues and return normalized JSON. A finance skill should not guess exchange rates when it can call one source and log the timestamp.

A practical pattern is to give every serious skill three commands: check, dry run, and execute.

bash run.sh check bash run.sh dry-run bash run.sh execute

The check command verifies credentials, dependencies, paths, and access. The dry-run command prints exactly what would change without writing externally. The execute command performs the action after prerequisites are proven. This makes the skill safer and easier to debug because every failure lands in a known phase.

I also like putting examples directly in SKILL.md. Keep them concrete. If the skill sends Slack messages, show the exact shape of a safe request. If it publishes articles, show the required metadata. If it touches files, state the workspace root and whether destructive actions require confirmation.

Security rules belong in the skill too. If your automation reads private data, say what it must never expose. If it sends public messages, require approval before posting. For a wider checklist, use OpenClaw security best practices before you give a skill write access to external systems.

Troubleshooting: Fix the Five Failures I See Most

The skill never triggers. Rename the skill folder and description around the user phrase, not the internal project name. Add one sentence that starts with “Use this when…” and lists the exact tasks it owns.

The wrong skill triggers. You probably have overlapping descriptions. Make each skill narrower. “Research” is too broad. “Reddit research for product messaging” is better. “Google Workspace calendar scheduling” is different from “Gmail search and drafting.”

The skill triggers but cannot run commands. Check the executable bit, shell path, and dependency versions. Run the command directly from the skill directory. If it fails there, fix the script before editing prose.

The skill leaks placeholders into the final output. Add a hard instruction that final answers must not contain placeholders, fake IDs, fake URLs, or invented metrics. Then move data collection into a helper command that returns real values.

The skill works locally but fails in cron. Cron usually has a thinner environment. Use absolute paths, avoid relying on interactive shell aliases, and log command output to a known workspace file. If a credential is loaded by your terminal profile, cron may not see it.

printenv | sort | sed -n '1,120p' crontab -l ls -la /Users/jkw/.openclaw/workspace

When I cannot tell whether the problem is routing or execution, I simplify the skill temporarily. I remove advanced instructions, keep one trigger sentence, and make the command produce a small visible result. Once that works, I add complexity back one layer at a time.

Near the end of any repair, I run a regression prompt. The prompt should be a real user request that previously failed. If it now works, save the prompt and the output in the skill folder or a workspace note. That gives the next operator a known-good test case instead of folklore.

FAQ: OpenClaw Skill Troubleshooting

How do I know whether OpenClaw loaded my skill? Run openclaw skills check and inspect both the personal and workspace skill directories. If the skill file is not under a loaded path, the agent cannot reliably use it.

What should I put in a skill description? Put the trigger condition, the owned workflow, and the boundary. A good description tells the agent when to use the skill and when not to use it.

Should a skill contain code or just instructions? Use instructions for judgment and deterministic scripts for fragile work. Parsing, validation, publishing, and API writes should usually live in helper scripts.

Why does my skill work in chat but fail from cron? Cron often lacks your interactive shell environment. Use absolute paths, explicit binaries, and environment checks inside the skill.

What is the fastest way to improve an unreliable skill? Add a check command, a dry-run command, and one saved regression prompt. That turns vague failures into repeatable evidence.

If you want the short version: make the skill easy to select, easy to test, and hard to misuse. Then connect it to the next implementation guide instead of packing every behavior into one giant instruction file. That is how skills stay useful after the demo.