OpenClaw Skill Not Loading
Fix a SKILL.md that exists on disk but is missing from the agent because of structure, precedence, eligibility, or session refresh.
A Skill directory exists, but OpenClaw does not show it or the agent never selects it for a matching task.
OpenClaw filters Skills at load time. A valid file can still be ineligible because of its location, required binaries, platform, configuration, or a higher-precedence Skill with the same name.
Check the file shape
The directory must contain SKILL.md with YAML frontmatter and Markdown instructions. At minimum, provide a clear name and description.
Check the load root and precedence
Workspace Skills take precedence over project-agent, personal-agent, managed, bundled, and extra-directory Skills. If two Skills use the same name, inspect the higher-precedence source.
Check eligibility
A Skill can require a binary, environment value, or platform. Confirm those requirements in the same host environment as the Gateway. A binary installed in your interactive shell may not be in the service PATH.
Refresh the session
OpenClaw snapshots eligible Skills when a session starts. The watcher can refresh changes, but a new session is the cleanest verification after structural edits.
Inspect the description
If the Skill loads but is never chosen, make its description explicit about both capability and trigger. Avoid a generic description that overlaps many other Skills.
Expected result
The Skill appears under its intended name in a new session and is selected for a matching test without overriding unrelated tasks.
Source notes
Technical facts on this page were checked against primary sources.