My OpenClaw skill isn’t loading

You installed a skill, tested it with a request that should trigger it, and nothing happened. The agent responded as if the skill does not exist. Or the skill was working fine last week and stopped loading without any obvious change. Skill loading failures are usually one of a small set of problems: the file is in the wrong location, the description tag is malformed, there is a formatting issue in the SKILL.md structure, or a conflict with another skill is causing the wrong one to activate. This article walks through each cause with diagnostic commands you can run directly in your OpenClaw chat and specific fixes for each failure mode.

Throughout this article you will see indented blocks like the ones below. Each one is a command you can paste directly into your OpenClaw chat. Your agent will run it and report back. You do not need to open a terminal or edit any files manually.

Step 1: Confirm the skill is visible to the agent

Before diagnosing anything about why a skill is not activating, confirm whether the agent can see the skill at all. A skill that is not in the available skills list cannot activate on any request regardless of how good its description is. This is the single fastest diagnostic step and eliminates the most common failure mode in under 30 seconds.

List every skill currently available to you. For each skill, show me: the skill name, the full path to its SKILL.md file, and the first sentence of its description tag. I am looking for whether [skill-name] appears in this list. If it does not appear, tell me that explicitly.

If your skill does not appear in the list, the problem is one of three things: the file is missing, the file is in the wrong location, or the SKILL.md has a structural problem that prevents it from being parsed. The next sections cover each of these in order.

If the skill does appear in the list, the problem is not a loading failure. The skill is present but not activating on the specific requests you are sending. Skip ahead to the section on description mismatches.

Step 2: Verify the file location

OpenClaw builds its skills list by scanning specific directories. A SKILL.md placed anywhere outside those directories is invisible to the agent. Even being one directory level off, such as placing the file at skills/my-skill.md instead of skills/my-skill/SKILL.md, is enough to make the skill undetectable.

Help me find a missing skill. Run: find /home/node/.openclaw/workspace/skills -name "SKILL.md" 2>/dev/null to list every SKILL.md file present. Also run: find /app/skills -name "SKILL.md" 2>/dev/null to check the system skills directory. Show me the full output of both commands. Then tell me: is there a SKILL.md for [skill-name] in either location? If yes, show me its full path.

The location field inside the SKILL.md itself must match the actual file path. If the file was placed manually and the location field points to a different path, that mismatch causes resolution failures when the agent tries to read the skill after finding it. Check both that the file exists and that its location field is accurate.

Read the SKILL.md for [skill-name] at the path you found and show me: (1) the name field, (2) the location field, (3) the first 200 characters of the description tag. Then confirm: does the location field value match the actual path of the file? If they do not match, tell me both values so I can see the discrepancy.

If the location field does not match the actual path, edit the location field to reflect where the file actually lives:

The location field in [skill-name]/SKILL.md says [wrong path] but the file is actually at [correct path]. Edit the SKILL.md and update the location field to the correct path. After saving, read the file back and confirm the location field now shows the correct value.

Step 3: Check the description tag structure

The description tag is how the agent identifies which skill to load for a given request. If the tag is missing, misspelled, uses incorrect opening or closing syntax, or is empty, the agent cannot match the skill against incoming requests. A skill with a broken description tag may appear in the skills list but will never activate.

Read the SKILL.md for [skill-name] and show me the complete description tag including the opening tag, the full description text, and the closing tag. I need to verify the tag structure is correct. Also tell me: is the tag named exactly “description” or is it something else? Are there any obvious formatting problems like missing closing tags, extra characters inside the tag delimiters, or the description text being outside the tags?

A correctly structured description tag looks like this:

<description>Use this skill when the user asks about X. Specifically for Y and Z requests. NOT for: A or B.</description>

Common structural problems and their fixes:

• Missing closing tag: The description text runs to the end of the file without a closing tag. The agent cannot determine where the description ends. Add the closing </description> tag.
• Tag misspelling: <desc> or <Description> instead of <description>. The tag name is case-sensitive. Correct to lowercase description.
• Description outside the tags: The description text appears before the opening tag or after the closing tag rather than between them. Move the text inside the tags.
• Empty description: The tags are present but the content between them is blank or whitespace only. Add meaningful description text between the tags.

The description tag in [skill-name]/SKILL.md has this problem: [describe the problem]. Fix it by [specific fix]. After fixing, read the file and show me the corrected description tag so I can confirm it looks right before testing the skill again.

Step 4: Fix description mismatches (skill visible but not activating)

If the skill appears in the available skills list and the description tag is correctly structured, but the skill still does not activate on your test requests, the description does not match the vocabulary or framing of the requests you are sending. The agent compares incoming requests against skill descriptions using semantic matching, but a description that uses substantially different terminology than real-world requests will produce low match scores and the skill will not be selected.

I am testing the skill [skill-name] but it is not activating. My test request was: “[exact request you sent]”. Read the skill’s description tag. Tell me: (1) Does the vocabulary in the description match the vocabulary in my request? (2) Does the description describe the exact type of request I sent, or a related but different type? (3) What would a request need to say for this description to match it reliably? Give me three example request phrasings that this description should match confidently.

When a description is too narrow or uses terminology that differs from how requests naturally arrive, the fix is to revise the description to more accurately reflect real request language. Do not make the description so broad that it matches everything. Instead, use the specific vocabulary that actually appears in the requests you send, include concrete examples of matching request types, and add explicit exclusions for similar request types that should not trigger the skill.

Rewrite the description tag for [skill-name] so it activates reliably on requests like “[example request 1]” and “[example request 2]” but does not activate on requests like “[non-matching request]”. The current description is: [current description text]. Write a replacement that uses the actual vocabulary from the requests it should match, is specific enough to avoid false matches, and stays under 100 words.

Step 5: Check for skill shadowing

If another installed skill has a description that overlaps with the skill you are trying to activate, the agent may consistently select the other skill instead. This produces the symptom of the correct skill never activating even on requests that seem perfectly matched to its description. The agent selects what it judges to be the best match, and if two descriptions are similar, one will win consistently.

Check whether any other installed skill is shadowing [skill-name]. My test request was: “[request]”. Read the descriptions of all installed skills. For each skill other than [skill-name]: could its description also match my test request? If any other skill’s description could match, which one would you select as the best match, and why would you pick it over [skill-name]?

When shadowing is confirmed, the resolution depends on how much the descriptions overlap. If the overlap is a genuine ambiguity that should be resolved by user intent, differentiate the descriptions by being more explicit about what separates the two skill use cases. If one skill should always take priority over the other for a specific request type, make the higher-priority skill’s description more specific to that request type so it scores higher as a match.

[skill-A] is shadowing [skill-B] on requests like “[request type]”. I want [skill-B] to handle these requests. Read both skills’ descriptions. Propose specific edits to one or both descriptions that would cause [skill-B] to win the match for “[request type]” requests while keeping [skill-A] correctly matched to the request types it should handle.

Step 6: Check file permissions and encoding

Less commonly, a SKILL.md file may exist at the correct path but be unreadable due to file permission issues, or contain encoding problems that prevent the agent from parsing the description tag correctly. These failures are more likely on skills that were transferred between systems using scp, rsync, or other file transfer methods that may not preserve permissions or encoding.

Check the file permissions and encoding for the SKILL.md at [path]. Run: ls -la [path] and show me the permissions. Then run: file [path] to check the file type and encoding. The file should be readable by the node user and should be UTF-8 text. Tell me if either check shows a problem.

If the file is not readable by the current user, fix the permissions:

Fix the file permissions for [path]. Run: chmod 644 [path]. After running, confirm the permissions now show as -rw-r--r-- in the ls output. Then try reading the file content to confirm it is accessible.

If the file has encoding issues (shown as non-UTF-8 in the file command output), the most reliable fix is to read the content, write it back explicitly as UTF-8:

The SKILL.md at [path] has an encoding problem. Read its contents as best you can despite the encoding issue. Then write the content back to the same path explicitly, which will save it as UTF-8. After writing, run file [path] again to confirm it now shows as UTF-8 text.

When a skill that was working stops loading

If a skill was working correctly and then stopped loading without any obvious change on your part, the most likely causes are an accidental file modification, a path change caused by a workspace reorganization, or a permission change. Run through the same diagnostic sequence starting from Step 1, but also check the git history for recent changes to the skill file.

A skill that was working has stopped loading. Run: git log --oneline --follow -- [path to SKILL.md] to see recent commits that touched this file. Show me the last five commits. Then run: git diff HEAD~1 HEAD -- [path to SKILL.md] to show what changed in the most recent commit that touched the file. Tell me if any of the recent changes could explain why the skill stopped loading.

If the git diff shows the description tag was modified or removed, restore it:

The git history shows that [specific change] was made to the SKILL.md. That change broke the skill. Restore the file to its last working state by running: git checkout [commit hash] -- [path to SKILL.md]. After restoring, read the file and confirm the description tag is intact. Then list available skills to confirm the skill appears in the list again.

If no git changes explain the failure, check whether the workspace directory structure changed. A reorganization that moved the skills directory, renamed a parent folder, or changed the workspace path itself will break all location field references that used absolute paths.

Check whether the workspace path has changed recently. Run: pwd to show the current working directory. Then read the location field from the SKILL.md at [path]. Does the location field path start with the same directory as the current working directory? If the workspace was moved or renamed, all location fields that use the old absolute path will be wrong.

Reinstalling a skill from scratch

When multiple diagnostic steps have not identified the problem, or when the SKILL.md is significantly corrupted, the fastest resolution is to reinstall the skill from its original source. For ClawHub skills, reinstallation is a single command. For manually created skills, it means rewriting the SKILL.md from scratch with the correct structure.

Reinstall the skill [skill-slug] from ClawHub. First, remove the current broken version by deleting the directory at [path]. Then run: npx clawhub install [skill-slug] to install a fresh copy. After the install completes, verify the skill appears in the available skills list and the description tag is intact. Then test with a request that should trigger it.

If the skill was manually created and needs to be rebuilt, document what the skill should do before deleting the broken version so you have a clear specification for the rewrite:

The skill [skill-name] needs to be rebuilt from scratch. Before I delete the broken version, read the current SKILL.md and extract: (1) the intended name, (2) the request types it is supposed to handle, (3) any specific instructions in the body that are still valid. Summarize this into a clear specification. Then I will delete the broken file and we will build a clean replacement using that specification.

Full diagnostic checklist

When a skill is not loading and the cause is not immediately obvious, run through this sequence in order. Each step rules out one category of failure before moving to the next. Do not skip steps based on assumptions about what the problem probably is. The fast assumptions are usually wrong, and skipping steps leaves the actual cause undiagnosed.

1. List available skills. Confirm whether the skill appears in the list. If it does not appear, the problem is file-level. If it does appear, the problem is activation-level. These are different diagnostic paths.
2. Check the file path. Find every SKILL.md file in the workspace. Confirm the skill’s SKILL.md is in a directory that OpenClaw scans. Confirm the file is at the path specified in its own location field.
3. Check the description tag. Read the SKILL.md and verify the description tag has correct opening and closing tags, is named exactly “description” in lowercase, and has non-empty content between the tags.
4. Check file permissions. Confirm the file is readable by the current user. Run ls -la and verify the permissions allow read access.
5. Check for shadowing. Compare the skill’s description against all other installed skills. If another skill’s description overlaps, determine which one the agent would select for your test request.
6. Check git history. If the skill was working and stopped, run git log on the file path to identify recent changes. Review the diff of the most recent change that touched the file.
7. Reinstall if above steps fail. If no specific cause is identified, reinstall from source or rebuild from scratch.

Walk me through the full skill diagnostic checklist for [skill-name]. Start from step 1: list all available skills and tell me whether [skill-name] appears. Based on whether it appears or not, continue to the appropriate next step. Report findings at each step and stop at the first step that identifies a problem. Do not continue past the identified problem until I confirm how to proceed.

Writing descriptions that load reliably

Most skill loading failures that are not file-location problems come down to description quality. A well-written description is specific, uses the actual vocabulary of real requests, draws clear boundaries around what the skill does and does not handle, and is short enough to be processed quickly without ambiguity. These properties are not just about style. Each one directly affects whether the skill activates when it should and stays quiet when it should not.

The most common description mistake is describing the skill by what it does internally rather than by what the user says to trigger it. A description that says “use this skill to process the user’s research query through the tavily search API and format the results as a structured report” describes the implementation, not the trigger. The user does not say “process my query through tavily.” They say “find me information about X” or “research Y for me.” The description should match the words the user actually types.

Review the description tag in [skill-name]/SKILL.md. Does the description use the vocabulary of what users say when they want this skill, or does it describe what the skill does internally? If it describes the implementation, rewrite it to describe the trigger: what would a user say when they want this skill to activate? Give me a revised description that uses natural request language and stays under 80 words.

The second most common description mistake is being either too broad or too narrow without explicit boundaries. A description that says “use this skill for web research” is too broad. It will match nearly every request that involves looking something up online, including requests that should be handled by other more specialized skills. A description that says “use this skill only when the user explicitly says they want a structured research report using the Tavily API” is too narrow. Most users will not say that.

The right description sits between these extremes: broad enough to match the natural language of real requests in its category, narrow enough to exclude requests that belong to other skill categories, and explicit enough that the agent can make a confident selection rather than an uncertain guess.

Evaluate the description breadth for [skill-name]. The current description is: “[current description]”. (1) Is this too broad? What unrelated request types might match it? (2) Is this too narrow? What valid requests for this skill might it fail to match? (3) Rewrite the description to hit the right balance: natural language trigger, clear category boundaries, explicit exclusions for the most likely false-positive request types.

Testing after a fix

After any fix to a SKILL.md, verify the fix actually works before treating the issue as resolved and moving on. A fix that appears correct based on the diagnosis may not change the actual behavior if the underlying problem was something slightly different than what was identified. Assumptions about why something broke are frequently wrong. Test with at least three different request phrasings: one that should clearly and unambiguously activate the skill, one that should clearly not activate it under any interpretation, and one borderline case that sits in the grey zone between this skill’s scope and an adjacent skill’s scope.

Test the skill [skill-name] after the fix I just applied. First tell me which skill you are selecting for this request, before giving the actual response: “[clear trigger request]”. Then tell me which skill you would select for this clearly out-of-scope request: “[request that should not trigger it]”. Then tell me which skill you would select for this borderline request: “[edge case request]”. Confirm in each case whether [skill-name] was selected or not selected, and why.

If the fix works for the clear trigger but the borderline case still produces unexpected behavior, the description boundary needs further refinement. A skill that handles the clear cases correctly but gets confused on borderline requests is usable but not fully tuned. Refine the description further based on the borderline test results until the skill activates consistently on the right requests and stays quiet on everything else.

The skill is correctly activating on clear trigger requests but the borderline case “[borderline request]” is still not behaving as expected. The skill selected for that request was [skill selected]. I want [correct skill] to handle that case instead. What needs to change in the descriptions of the two competing skills to make [correct skill] win for “[borderline request]” without breaking the clear cases for either skill?

Skills after an OpenClaw update

When OpenClaw updates, skills should continue to work without modification. Skills are passive text files and do not depend on specific gateway internals. However, an update that changes the workspace directory structure, the path from which the gateway reads skill files, or how skill descriptions are parsed could break existing skills. If skills stop loading after an OpenClaw update, this is the category to investigate.

OpenClaw was recently updated and several skills stopped loading. Check whether the update changed how skills are discovered. (1) What is the current OpenClaw version? (2) Are there any release notes or changelog entries for recent versions mentioning changes to skill loading, workspace paths, or SKILL.md format? (3) List all currently available skills. Compare this to the full list of SKILL.md files in the workspace. Which skills are present on disk but not appearing in the available list?

If an OpenClaw update changed the expected path for skills and that is causing loading failures, the fix is to move the skill files to the new expected location or update the workspace configuration to point to the existing location. Do not modify the SKILL.md content itself for a path problem. The content is correct. Only the file location needs to change.

The OpenClaw update moved the expected skills directory location. My existing skills are at [old path] and the new expected location is [new path]. Move all the SKILL.md files from their current locations to the new expected directory structure. After moving, update the location field in each SKILL.md to reflect the new paths. Then confirm all moved skills appear in the available skills list.

Preventing skill loading failures before they happen

Most skill loading failures are preventable. The diagnostic steps in this article exist because something went wrong during installation, editing, or a workspace change. The prevention steps are things that stop those failure modes from occurring in the first place, so you spend less time debugging and more time using your skills for actual work.

The single highest-leverage prevention step is verifying the skills list immediately after every installation. Before testing the skill’s actual behavior, confirm it appears in the available skills list. This two-second check catches location problems, missing fields, and tag format issues while the installation is fresh in context, rather than discovering them hours or days later when the skill does not activate on an important request.

Run my post-installation verification checklist for the skill I just installed. (1) Does the skill appear in the available skills list? (2) Is the SKILL.md at the path specified in its location field? (3) Is the description tag correctly structured with opening and closing tags? (4) Does the description use vocabulary that matches the requests I would naturally send? If all four checks pass, the skill is correctly installed. If any check fails, tell me exactly which one failed and what the specific problem is.

The second prevention step is documenting customizations. When you edit a SKILL.md from ClawHub, whether to fix the description, adjust instructions, or remove sections that do not apply to your setup, record what you changed and why. A comment block at the top of the file is sufficient. Without this documentation, a reinstall or update will silently overwrite your customizations, the skill will revert to generic behavior, and you will not know why it changed until you compare the new file to your memory of what the old one said.

After editing the SKILL.md for [skill-name], add a documentation block at the very top of the file. The block should record: the date of the edit, what was changed (be specific about which fields or instruction lines were modified), and why the change was made. Format it as an HTML comment so it does not interfere with the skill parsing. This block should survive any future reads and give a clear record of what is custom about this installation.

The third prevention step is keeping a skills inventory. Whether you track this in TOOLS.md, MEMORY.md, or a dedicated file, maintaining a list of what is installed, what each skill does, and when it was last verified working gives you a reference point for debugging. When a skill stops working, the inventory tells you when it last worked, whether it was recently edited, and whether any other changes to the workspace could have affected it. Without an inventory, every debugging session starts from scratch with no baseline to compare against, no history to reference, and no record of what the last known-good state was.

Update my skills inventory to reflect the current state of all installed skills. For each skill in my workspace: add or update an entry showing the skill name, its purpose in one sentence, the request types it handles, the installed path, the date it was last verified working, and any known customizations from the original source. Write this to TOOLS.md under a Skills Inventory section, creating the section if it does not exist.

Frequently asked questions

No. Skills are read from disk each time they are activated, not cached at gateway startup. A fix applied to a SKILL.md takes effect immediately on the next request that triggers the skill. You do not need to restart the gateway, run any reload command, or start a new chat session. The fix is live as soon as the file is saved.

Two possibilities. First, the agent is selecting the skill based on the description match but the instruction body has problems: ambiguous steps, references to unavailable tools, or instructions that conflict with higher-priority rules in SOUL.md or AGENTS.md. Second, the agent is selecting a different skill that has a similar name and reporting the wrong skill as available. Verify the exact path of the SKILL.md that is being read and compare the instructions to what you expect to see.

The agent will use whichever one it encounters first during the skills directory scan. There is no defined priority between two skills with identical or very similar descriptions, which means the selection may be inconsistent across requests. Remove the duplicate and keep only the version you want active. Having two versions of the same skill is a reliable source of confusing and hard-to-reproduce behavior.

The install command reporting success means the download completed, but it does not guarantee the file landed in a location that OpenClaw scans. Check where the clawhub command actually wrote the files by running the find command from Step 2. If the files landed in a path that OpenClaw does not scan, move them to the correct skills directory. The most common cause is the clawhub command being run from a different working directory than expected, causing the relative install path to resolve incorrectly.

Session-to-session inconsistency in skill loading usually means two things are happening: the skill is loading correctly in sessions where the agent happens to look in the right directory, and failing in sessions where it does not. This can happen if the skills directory path resolves differently depending on the working directory set at session start, or if there are two workspace locations and the agent connects to different ones in different sessions. Check the workspace path at the start of a failing session versus a working session to see if they differ.

There is no hard file size limit for SKILL.md files, but extremely long skills can affect performance. A skill that runs to thousands of lines of instructions will take longer to read and process than a focused 30-line skill. If a skill file is very large and the agent appears to struggle with it, trim the instructions to the essential steps. Skills work best when they are tightly focused and directly instructional. Instructions that can be inferred from context or that duplicate what SOUL.md or AGENTS.md already handles do not need to be in the skill.

If the description tag is correctly structured and the file is at the right path with readable permissions, but the skill still does not appear in the list, check whether the SKILL.md is missing its name or location fields entirely. OpenClaw requires these fields to register a skill. A file that only has a description tag and instruction body but is missing the name and location header fields may be parsed as having incomplete metadata and excluded from the available list. Read the full SKILL.md and verify the name field and location field are both present at the top of the file, correctly formatted.

Ask the agent to read the skill file at its exact path and report the first three instructions. Compare those instructions to what you expect the skill to contain. If the content matches your expected instructions, the correct file is being loaded. If the content is different, the agent is either reading a different file or the file has been modified in ways you are not aware of.

Go deeper