OpenClaw skill not showing? Find which loading gate failed

If an OpenClaw skill is not showing, do not reinstall it blindly. Run openclaw skills list, openclaw skills check, and openclaw skills info <name> first. A skill absent from the list has a discovery or frontmatter problem. A listed but unready skill failed an eligibility gate. A ready skill missing from one agent is usually filtered by that agent's allowlist or frozen in an older session snapshot. A skill that loads on the host but fails during use has an execution-environment problem, commonly a missing sandbox dependency or secret.

openclaw skills list
openclaw skills check
openclaw skills info my-skill
openclaw --version

OpenClaw skill not showing: diagnose it at a glance

This distinction matters because “not showing” is not one failure. Deleting sessions cannot fix malformed frontmatter. Restarting the gateway cannot satisfy a missing binary. Adding an API key to the host cannot put that key inside a Docker sandbox. Diagnose the stage before changing state.

Why is the skill absent from openclaw skills list?

Complete absence means OpenClaw did not construct a valid skill entry. Start with the smallest valid shape:

<workspace>/skills/my-skill/SKILL.md

---
name: my-skill
description: Do one specific reusable job
---

# My skill

Instructions for the agent.

The filename is case-sensitive: SKILL.md. The opening frontmatter fence must be the first content in the file, and both name and description are required. Use a lowercase name made from letters, digits, and hyphens. Keep the directory name aligned with the frontmatter name so logs, configuration, and operator expectations all point at the same thing.

Check the active skill root, not the folder you remember

Current OpenClaw loads skill roots in this precedence order:

1. <workspace>/skills — highest priority, scoped to that workspace;
2. <workspace>/.agents/skills;
3. ~/.agents/skills;
4. ~/.openclaw/skills — shared managed/local skills;
5. bundled skills;
6. skills.load.extraDirs — lowest priority.

When two roots contain the same skill name, the higher-precedence entry wins. That can look like a change “did not load” when OpenClaw actually loaded a different copy. Run skills info and inspect the source path instead of editing every copy you can find.

Fix the OpenClaw 2026.7.1 trailing-comma regression

OpenClaw 2026.7.1 had a reproducible parser failure: JSON5-style trailing commas inside a YAML metadata flow mapping could make a valid, correctly located workspace skill disappear from skills list, skills check, and skills info with no matching log line. The immediate workaround is to remove the trailing commas:

# Avoid on affected 2026.7.1 builds
metadata: { "openclaw": { "requires": { "env": ["EXAMPLE_VAR"], }, }, }

# Portable form
metadata:
  openclaw:
    requires:
      env:
        - EXAMPLE_VAR

The upstream fix was merged on July 16, 2026 and unified skill entry points on the canonical frontmatter parser. The current stable tag, v2026.7.1-2, contains that parser. If you are on the original 2026.7.1, back up your state, review the release notes, and update to 2026.7.1-2 or a later stable build. Do not move to a beta merely to solve this symptom. The minimal upstream reproduction and the merged parser fix document the boundary precisely.

Why is the skill listed but not ready?

Once a skill appears in the list, stop changing paths and frontmatter delimiters. Discovery succeeded. OpenClaw is now evaluating whether the skill can run in this environment. Read the result of openclaw skills check and inspect these gates:

• requires.bins: every named executable must exist on the gateway host's PATH.
• requires.anyBins: at least one named executable must exist.
• requires.env: every variable must exist in the host process or be supplied by the skill entry.
• requires.config: every named openclaw.json path must resolve truthy.
• os: the current platform must be included.
• skills.entries.<name>.enabled: an explicit false disables the skill.

Do not “fix” a dependency gate by deleting it unless the instructions truly work without that dependency. Gates prevent an agent from being promised a capability that will fail halfway through a task. Install or configure the missing prerequisite, then run the check again.

Why can one agent see the skill but another cannot?

OpenClaw can apply a final skill allowlist per agent. The subtle rule is that an explicit agent list replaces inherited defaults; it does not merge with them:

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" },
      { id: "researcher", skills: ["docs-search"] },
      { id: "locked-down", skills: [] }
    ]
  }
}

Here, writer inherits github and weather. researcher gets only docs-search, not all three. locked-down gets no skills. Match allowlist values to the skill's frontmatter name, not an old folder name or ClawHub display title.

Scope is separate from allowlisting. A skill under one agent's workspace is not automatically shared with every other workspace. Put genuinely shared skills in an appropriate shared root, then keep per-agent allowlists narrow. The broader OpenClaw skills guide explains the difference between instructions, dependencies, and execution permissions.

Why is a new skill missing only from an existing session?

OpenClaw snapshots the eligible skill catalog when a session starts. Its file watcher can detect changes and refresh the effective catalog for a later turn, but an existing session can still carry the catalog it began with. After installing or materially changing a skill, start a fresh session with /new and test there before restarting the entire gateway.

A gateway restart is appropriate when skills.load.watch is disabled, the watcher is unhealthy, or a configuration change is not reflected by a new session. It should not be the first move. “The file is discovered in a new session” and “the instructions reliably trigger” are also different tests: invoke the skill explicitly once, then try the natural-language request its description is supposed to match.

Why does the skill load on the host but fail in a sandbox?

Discovery and eligibility happen against the host environment. A Docker sandbox does not inherit every host variable or binary. In particular, skills.entries.*.env and apiKey apply to host runs, not automatically to sandboxed execution. A skill can therefore be visible and “ready” yet fail when its script runs inside the sandbox.

Deliver the dependency to the environment that executes it: install the binary in the sandbox image and pass configuration through the sandbox's supported environment or a mounted secret. Then verify from inside that environment. Do not copy secrets into SKILL.md, prompts, logs, or a public skill package.

Why are symlinked or extra-directory skills skipped?

Workspace and extra-directory roots are containment boundaries. A skill folder symlink that resolves outside its configured root is skipped unless its real target is explicitly trusted with skills.load.allowSymlinkTargets. This protects the loader from following an innocent-looking workspace path into arbitrary host files.

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true
    }
  }
}

Keep both lists narrow. Do not point extraDirs or allowSymlinkTargets at your home directory or an entire projects tree. If the path is not intentionally shared, copy or install the skill into the active workspace instead. If ClawHub installed the wrong copy or an update changed its files, use the safe ClawHub skill update checklist rather than editing multiple generated locations.

Frequently asked questions

Why is my OpenClaw skill not showing in the skills list?

If the skill is completely absent from openclaw skills list, OpenClaw did not discover a valid skill entry. Check that the file is named SKILL.md, lives below an active skill root, and has leading YAML frontmatter with a name and description. On OpenClaw 2026.7.1, JSON5-style trailing commas in a metadata mapping could also hide the skill; remove the commas or update to 2026.7.1-2 or later.

Why does OpenClaw list my skill but mark it unavailable?

A listed but unavailable skill was discovered and then rejected by an eligibility gate. Inspect openclaw skills check and openclaw skills info <name>. Typical causes are a missing required binary or environment variable, a false requires.config value, an incompatible OS gate, or skills.entries.<name>.enabled set to false.

Why can one OpenClaw agent see a skill but another cannot?

Each agent can have a final skills allowlist. An explicit agents.list[].skills value replaces the default list; it does not merge with it. Add the skill's frontmatter name to the intended agent's list, or omit the per-agent list to inherit the defaults. A workspace skill is also scoped to that agent's workspace unless installed in a shared root.

Do I need to restart OpenClaw after installing a skill?

Usually you need a new agent session, not a full gateway restart. OpenClaw snapshots eligible skills when a session starts. The watcher can refresh changed skill files for a later turn, but an older session may retain its prior catalog. Start a new session with /new; restart the gateway only when the watcher is disabled or configuration changes are not being picked up.

Why does an OpenClaw skill work on the host but fail in a sandbox?

Skill eligibility and host execution do not prove that the sandbox has the same environment. skills.entries.*.env and apiKey are injected into host runs, not into a Docker sandbox. Deliver required binaries and credentials through the sandbox configuration or a mounted secret, then test the skill inside that execution environment.