#Do custom skills get shown in the openclaw skills list?

1 messages · Page 1 of 1 (latest)

clever duneBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

mild treeBOT
#

@green crow Yep — custom skills show up in openclaw skills list as long as OpenClaw is loading them from one of the skill directories.

1) Make OpenClaw load your custom skill (local list)

Put your skill folder in one of these locations:

  • Per-workspace (most common): <your workspace>/skills/<skill-name>/SKILL.md
  • Global on that machine: ~/.openclaw/skills/<skill-name>/SKILL.md
  • Some other folder: add it via skills.load.extraDirs in ~/.openclaw/openclaw.json

From the docs, precedence is:
<workspace>/skills → ~/.openclaw/skills → bundled → skills.load.extraDirs (lowest)

Then check it:

openclaw skills list
# 
clawhub login
clawhub publish ./path/to/your-skill --slug your-skill --name "Your Skill" --version 1.0.0 --tags latest
# or to back up/sync many:
clawhub sync --all

Docs: https://docs.openclaw.ai/tools/clawhub

If you tell me which “skills list” you mean (CLI list vs macOS Skills UI vs ClawHub), I can give the exact steps for your setup (local/remote mode matters too: skills must live on the gateway host).

#

@green crow If it’s not showing up at all in openclaw skills list, it’s almost always one of these:

1) You added it to the wrong workspace (or wrong machine)

OpenClaw loads workspace skills from the workspace configured on the gateway host.

Please run and paste the relevant bits:

openclaw --version
openclaw status
openclaw gateway status

In particular, I’m looking for what it says the workspace path is, and whether your CLI is talking to a remote gateway (common: gateway on VPS, you edited local files → won’t show).

If you’re using multiple agents, each agent has its own workspace. Easiest “make it visible everywhere” option: put the skill in:

#

~/.openclaw/skills/<skill-name>/SKILL.md (global on that gateway machine)

2) Filename / folder structure mismatch

It must be exactly:

<workspace>/skills/<skill-folder>/SKILL.md (note the exact caps)

Quick sanity check:

ls -la "<workspace>/skills"
find "<workspace>/skills" -maxdepth 2 -name SKILL.md -print

3) SKILL.md frontmatter doesn’t parse → skill gets skipped

The loader is picky. Minimal valid example:

# 
---
name: my-skill
description: Does X
---

If you paste the first ~30 lines of your SKILL.md, I can spot if the frontmatter/metadata format is the issue.

4) Watcher is off / gateway needs restart (less common)

If skills.load.watch is disabled in config, you may need a restart:

openclaw gateway restart

Also run:

# 
openclaw skills check

That often prints the exact reason it’s ignoring something.

If you paste: (a) your workspace path from openclaw status, and (b) the first lines of SKILL.md, we’ll nail it quickly.

#

@green crow Two things jump out immediately:

1) Your path has a typo: workplace vs workspace

OpenClaw won’t scan ~/.openclaw/workplace/... (unless you explicitly configured that as your workspace).

Default workspace is:

~/.openclaw/workspace

So the expected location is:

~/.openclaw/workspace/skills/bnb-sender/SKILL.md

Quick check:

# 
openclaw status

and look for the Workspace path it reports — put the skill under that folder.

2) Your SKILL.md will load, but tools: won’t do what you think

OpenClaw skills are instructions, not a way to define new executable “bash tools” like send_bnb. The openclaw skills list command should still list the skill, but tools: is an unknown frontmatter field (it’ll show as a warning in openclaw skills check).

Run:

openclaw skills check

That will usually tell you what it found and any warnings (including unknown fields, name mismatch, etc).

#

Minimal “known-good” SKILL.md

If you want to avoid parsing/validation weirdness, start with:

---
name: bnb-sender
description: Send BNB on BSC (always ask for confirmation first).
---

# bnb-sender

(put your instructions here; reference files with `{baseDir}`)

If you do those and it still doesn’t show

Paste the output of:

# 
openclaw status
openclaw skills check

and I can tell exactly what directory it’s scanning and why it’s skipping it.

mild treeBOT
#

@green crow That skills check output is fine (and unrelated to the custom skill). The reason your skill isn’t showing is almost certainly location.

1) Your path is wrong: workplace vs workspace

You wrote:

~/.openclaw/workplace/skills/...

but the default workspace is:

~/.openclaw/workspace

So move it to either:

Workspace skill (per workspace):
~/.openclaw/workspace/skills/bnb-sender/SKILL.md

or Managed skill (global on that machine, easiest to avoid workspace confusion):

#

~/.openclaw/skills/bnb-sender/SKILL.md

Also make sure the folder name matches the skill name exactly (bnb-sender).

2) Verify what workspace OpenClaw is actually using

Run:

openclaw config get agents.defaults.workspace

Whatever it prints, that’s the <workspace> you should use → put your skill under <workspace>/skills/....

(If OPENCLAW_PROFILE is set, the default can become ~/.openclaw/workspace-<profile>.)

3) Confirm it loaded

After moving the folder, run:

# 
openclaw skills list
openclaw skills info bnb-sender

If skills info bnb-sender says “not found”, it’s still in the wrong directory.

Note on your SKILL.md

Your tools: block won’t register as a new executable tool in OpenClaw (skills are instructions + gating, not “define a bash tool”), but it should still list once it’s in the correct folder.

Docs: https://docs.openclaw.ai/tools/skills and https://docs.openclaw.ai/cli/skills

If you paste the output of openclaw config get agents.defaults.workspace + openclaw skills list | grep bnb -n (or just the relevant lines), I can tell you exactly what it’s seeing.

green crow
#

ok now i see it on the list but when i text the ai to do it, it doesnt recognize the skill. I even added a simple skill to test:

name: one
description: Special reply when user sends "one".

One Skill

When the user sends the exact message "one", reply literally with:

one
Do not add any extra text, explanations, or formatting. Only output the word one.

and this aint working either but it shows on the list

mild treeBOT
# green crow ok now i see it on the list but when i text the ai to do it, it doesnt recognize...

@green crow What you’re expecting (“I type one and it auto-triggers the skill”) isn’t how OpenClaw skills work.

Skills are not message triggers

A skill showing up in openclaw skills list just means it’s discoverable. In normal chat, the model only maybe uses a skill if it decides to read the SKILL.md based on the situation. For a bare message like one, most models won’t think “I should go load a skill file”.

How to actually run/test a skill

Use the built-in skill command:

  • Send (in chat):
    /skill one one
    (/skill <name> [input] — so you’re explicitly telling OpenClaw “run skill one with input one”)

Also try:

  • /skill one
# 
  and see what it replies.

If you’re on Telegram/Discord and native skill commands are enabled, you may also get a direct command for the skill (skill names get sanitized; e.g. `bnb-sender` often becomes `/bnb_sender`). But `/skill one ...` always works.

Docs: https://docs.openclaw.ai/tools/slash-commands (see “/skill” + skill commands)

### Verify the model is even seeing the skill in context
In chat, run:
```text
/context detail

That will show whether the skills list is actually included in the prompt for that session.

About your bnb-sender skill

That tools: frontmatter won’t define a new executable tool in OpenClaw (it’ll be treated as an unknown frontmatter field). If you want “send BNB” to be a real tool, you’d need a plugin/tool implementation, not just a skill file.

# 

If you tell me what surface you’re using (Telegram? Discord?) I can tell you the exact command name you should see for `bnb-sender` and whether `commands.nativeSkills` needs a restart.
green crow
#

im using Telegram and im not seeing my added skills in /context detail

mild treeBOT
# green crow im using Telegram and im not seeing my added skills in /context detail

@green crow On Telegram, the key detail is: only “eligible” skills are injected into the prompt, and the skills list is snapshotted per-session.

So if your skill shows up in openclaw skills list but not in /context detail, it usually means one of these:

1) Your skill is not “eligible” (so it won’t be in the prompt)

Run this on the gateway host:

openclaw skills list --eligible
# or:
openclaw skills check

Your skill (one, bnb-sender) must appear under Eligible / Ready to use.
If it’s missing there, paste openclaw skills info one (and/or ... info bnb-sender) and we’ll see why it’s being filtered.

2) Your Telegram chat session started before you added the skill

#

OpenClaw snapshots eligible skills when the session starts. New skills often won’t appear until you start a fresh session.

In Telegram, send:

/new

Then immediately:

/context detail

Now you should see your custom skill listed in the skills section.

3) Even when skills are in context: they don’t “auto-trigger”

#

Typing one will not automatically run a skill. To explicitly invoke it, use:

/skill one one

(That’s the reliable way to test.)

If you paste:

  1. openclaw skills check (after adding the skills), and
  2. the /context detail output after /new in Telegram,
    I can pinpoint exactly whether it’s “not eligible” vs “old session snapshot” vs “invocation expectation”.
green crow
#

when my SKILL.md is used I want to run an external file called ./send_bnb.sh". How to do it?

mild treeBOT
# green crow when my SKILL.md is used I want to run an external file called ./send_bnb.sh". H...

@green crow To run ./send_bnb.sh from a skill, you can’t do it via tools: in SKILL.md (OpenClaw doesn’t treat that as “define a new tool”). A skill is instructions, so the only way to execute a script is to have the model call an existing exec tool.

In practice you have two options:

Option A (recommended): run the script via nodes.run (system.run)

  1. Put the script in the skill folder and make it executable:
# on the machine where the command will run
chmod +x ~/.openclaw/workspace/skills/bnb-sender/send_bnb.sh
  1. Make sure you have a node that can execute commands on that machine.
    If you’re on Linux/Windows, start a headless node host and pair it:
# 
openclaw node run --host <your-gateway-host> --port 18789

(Then approve the node pairing in the gateway UI / prompts.)

Docs: https://docs.openclaw.ai/nodes#headless-node-host-cross-platform

  1. In your SKILL.md, instruct the agent to call nodes → run, and use {baseDir} so the path is correct (don’t rely on ./):
---
name: bnb-sender
description: Send BNB on BSC (requires explicit confirmation).
---
# 
When the user asks to send BNB:
1) Collect `to` and `amount`.
2) Repeat them back and ask for an explicit "CONFIRM".
3) Only after CONFIRM, execute:

Use the nodes tool with action "run" to run:
- cwd: "{baseDir}"
- command: ["bash", "{baseDir}/send_bnb.sh", "<to>", "<amount>"]

That will trigger an exec approval flow (good). Docs: https://docs.openclaw.ai/tools/exec-approvals

Option B: make it a real “tool” (plugin)

If you want a deterministic /send_bnb to=
 amount=
 style command with strict input validation (highly recommended for anything involving money), you’ll want to implement a plugin tool rather than relying on the model to run shell scripts.

#

One more important note: automating crypto sends is prompt-injection bait. Keep it DM-only, require explicit confirmation every time, and don’t store private keys in the skill file. If you tell me where the gateway is running (Linux VPS? local machine?) and whether you already have a node paired, I can give you the exact nodes.run shape to use.

undone wyvern
#

Hi Guys, I'm bumping this thread because I'm having a similar issue and I can't figure out why it's happening, even after trying everything above.

The skill I've made is not showing up on openclaw skills list or the dashboard

  • Output of openclaw config agents.defaults.workspace: /home/node/.openclaw/workspace
  • Output of ls /home/node/.openclaw/workspace/skills/deepseek-balance/: SKILL.md references scripts (meaning it is supposedly in the correct folder
  • First few lines of my SKILL.md:
---
name: deepseek-balance
description: Check DeepSeek API balance and usage. Use when the user asks about -  "Check my DeepSeek balance", "How much API credit do I have left?", "What's my DeepSeek usage?", "DeepSeek account status", "API token balance", or any query related to DeepSeek platform credits, usage, or account information.
---

# deepseek-balance

## Quick Start

  • Output of the quick_validate.py script in the skill-creator skill: Skill is valid! (meaning the validations shoudl have passed)

  • I even tried moving the skill to where the rest of the system skills are in the system files, and it is still not finding it. Any ideas?

It goes without saying that I've been restarting openclaw every time I make a change 😅

mild treeBOT
# undone wyvern Hi Guys, I'm bumping this thread because I'm having a similar issue and I can't ...

Short answer: yes — custom skills are shown. If yours doesn't appear, the cause is nearly always one of these: the CLI/gateway is scanning a different workspace than the one you edited, the skill was parsed/merged away, or the skill is present but gated/hidden by config or session snapshot. Below is a focused troubleshooting checklist (copy/paste the commands and report back the outputs you see).

  1. Confirm which workspace the CLI is actually scanning
  • Run: openclaw skills list --json
  • Look at the workspaceDir field (this is the folder the CLI scanned). If you don't have jq, just run the command and read the JSON.
  • Verify the file exists where that JSON says:
    • ls -la <workspaceDir>/skills/deepseek-balance
    • head -n 10 <workspaceDir>/skills/deepseek-balance/SKILL.md

Why: the CLI looks at the default agent workspace resolved from config/env. Common mismatch causes: different container/user, OPENCLAW_PROFILE, or a per-agent workspace override.

  1. See if the skill was loaded at all
  • Run: openclaw skills list --json | jq '.skills[] | {name,source,eligible,disabled,primaryEnv,homepage}'
  • Or directly: openclaw skills info deepseek-balance --json

What to expect: if the skill is loaded you'll see an entry (with source telling where it came from). If not present, the loader didn't see it.

#
  1. If it's present but not usable / not in the agent prompt
  • Check eligibility & missing requirements: openclaw skills check -v or openclaw skills list -v
  • If metadata.openclaw in frontmatter requires bins/env/os/config that are missing, the skill will be marked ineligible. (Note: the CLI shows all loaded skills by default; --eligible filters to ready ones.)
  1. Quick checks for common file/parse problems
  • Ensure frontmatter is a top-level YAML block starting with --- and closed with --- (no hidden BOM before the first ---).
    • Check for BOM: xxd -p -l 3 <workspaceDir>/skills/deepseek-balance/SKILL.md — if output is efbbbf you have a UTF-8 BOM (remove it).
  • Validate file name & location: must be exactly SKILL.md (case sensitive) directly inside <skill-dir>/.
  • Try a minimal test skill to verify scanning works:
    • mkdir -p <workspaceDir>/skills/hello_test && cat > <workspaceDir>/skills/hello_test/SKILL.md <<'EOF'\n---\nname: hello_test\ndescription: test skill\n---\nEOF
    • Then openclaw skills list --json | jq '.skills[] | select(.name==\"hello_test\")'
  1. Bundled vs managed vs workspace confusion
  • Skills are loaded from (lowest→highest): extraDirs → bundled → managed (~/.openclaw/skills) → workspace (<workspace>/skills). Workspace wins on name conflicts.
  • If you copied the skill into the bundled location (installed node_modules), that may be subject to skills.allowBundled config (an allowlist). Check:
    • openclaw config get skills.allowBundled
  • If you used ~/.openclaw/skills, check openclaw config get skills.entries in case a skill override disables it.