My skill on ~/.openclaw/skills doens't work fine | Friends of the Crustacean 🦞🤝 | Page 1

uneven cargo Apr 23, 2026, 3:50 PM

#

I create a personal skill that isn't on Clawhub.

https://github.com/appmaxbrasil/openclaw-max-banking-skill

How I clone that:

I created an installer: https://github.com/appmaxbrasil/openclaw-max-banking-skill/tree/feat/installer-script

The SH file: https://github.com/appmaxbrasil/openclaw-max-banking-skill/blob/feat/installer-script/installer/install.sh

And I execute for example:

curl -fsSL https://raw.githubusercontent.com/appmaxbrasil/openclaw-max-banking-skill/feat/installer-script/installer/install.sh | bash

This create to me the directory on ~/.openclaw/skills/max-banking corretly:

After that the script reset my gateway and I executed /new to reset my session.

When I type for example:

/context window list:

Skills list (system prompt text): 4,395 chars (~1,099 tok) (8 skills)
Skills: healthcheck, max-banking, mcporter, node-connect, skill-creator, taskflow, taskflow-inbox-triage, weather
My skill max-banking are there.

And executing openclaw skills list, my skill appear as ready.

And I tried for example:
"Qual meu saldo?"

And openclaw couldn't finde my SKILL.md and execute corretly the command.

Openclaw tried to spawn an agent to execute but failed, after that tried for example execute "openclaw max-baking exec" but got and error because this don't exists.

lilac raptorBOT Apr 23, 2026, 3:50 PM

#

simple zincBOT Apr 23, 2026, 3:50 PM

#

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

lilac raptorBOT Apr 23, 2026, 3:50 PM

#

dry lanceBOT Apr 23, 2026, 3:53 PM

#

Let me check the docs and the skill-loading logic, because the fact that it shows up in /context window list but still gets ignored usually means the skill is loaded but not being selected.

#

If max-banking shows up in both openclaw skills list and /context window list, the install itself is probably fine.

What’s failing is the next step: skill selection.

OpenClaw does not preload the full SKILL.md. It only gives the model a small skills catalog with:

name
description
location

Then the model decides whether to read that SKILL.md.
If it invented openclaw max-baking exec, that usually means it never selected/read the skill and started hallucinating.

First, please paste:

#

openclaw --version
openclaw skills info max-banking

And try this as a diagnostic:

/skill max-banking qual meu saldo?

If /skill max-banking ... works, then your skill is installed correctly and the problem is just discovery/matching.

Most likely causes:

The description is not distinctive enough for routing
The one-line frontmatter description: is what matters first, not the long body.

#

Your skills prompt got compacted
If skills.limits.maxSkillsPromptChars is too low, OpenClaw can fall back to a compact list and the model has less context for choosing the right skill.
Model weakness
Smaller/local/weaker models are much more likely to skip the read SKILL.md step and invent commands.

I’d tighten the skill description to something very literal, for example:

description: "Use for Max Bank requests: saldo, conta, PIX, boleto, conectar conta. Trigger on: 'qual meu saldo', 'saldo', 'quanto tenho', 'meus dados da conta', 'fazer pix', 'pagar boleto'."

Also check whether you have a custom low budget here:

skills.limits.maxSkillsPromptChars
agents.list[].skillsLimits.maxSkillsPromptChars

#

Docs:

If you paste the outputs of openclaw --version and openclaw skills info max-banking, I can narrow it down pretty fast.

uneven cargo Apr 23, 2026, 3:56 PM

#

openclaw -v
OpenClaw 2026.4.22 (00bd2cf)

openclaw skills info max-banking
\U0001f99e OpenClaw 2026.4.22 (00bd2cf) \u2014 Making 'I'll automate that later' happen now.

\U0001f4e6 max-banking \u2713 Ready

Operacoes financeiras da conta Max Bank via MCP. Use quando o usuario pedir saldo, fazer PIX (chave ou QR copia e cola), pagar boleto, conectar conta Max, ou enviar codigos PIX (00020...), linhas digitaveis de boleto ou imagens de QR/codigo de barras.

Details:
Source: openclaw-managed
Path: ~/.openclaw/skills/max-banking/SKILL.md
Homepage: https://github.com/appmaxbrasil/openclaw-max-banking-skill

Requirements:
Binaries: \u2713 mcporter, \u2713 node

Tip: use openclaw skills search, openclaw skills install, and openclaw skills update for ClawHub-backed skills.

dry lanceBOT Apr 23, 2026, 3:58 PM

#

Nice, that confirms a lot.

Your skill is loaded correctly:

OpenClaw 2026.4.22
max-banking is Ready
it is coming from ~/.openclaw/skills/max-banking/SKILL.md
it is visible in the prompt

So this is not a clone/install/path problem.

The bad openclaw max-baking exec call is the giveaway, that’s the model hallucinating after it failed to select/read the skill, not the skill loader failing.

Two important details here:

OpenClaw does not preload the full SKILL.md
It first only sees the skill’s one-line description, then decides whether to read the file

#

So the first thing I’d do is make the frontmatter description much more literal and trigger-focused, for example:

description: "Max Bank actions: saldo, conta, PIX, boleto, conectar conta. Use for: 'qual meu saldo', 'ver saldo', 'quanto tenho', 'meu saldo', 'fazer pix', 'pagar boleto'."

A shorter, more direct description usually routes better than a long one.

Also try this right now:

/skill max-banking qual meu saldo?

That is the best diagnostic.

If /skill max-banking ... works, your skill is fine and only the automatic discovery is flaky.

#

If /skill max-banking ... also fails, then I’d suspect a real regression/bug in 2026.4.22.

So my recommendation is:

test /skill max-banking qual meu saldo?
shorten/tighten the description:
if you’re using a weaker/local model, test once with a more tool-reliable one, this exact “invented command” behavior is common there

Docs:

If you want, paste the result of /skill max-banking qual meu saldo? and I can tell you immediately whether this is routing or a real bug.

uneven cargo Apr 23, 2026, 4:03 PM

#

/skill max-banking "Qual meu saldo?"

Still gotten an error

#

Could you help me? That

dry lanceBOT Apr 23, 2026, 4:08 PM

#

Let me check one thing in your installer, because I may have spotted something sneaky.

#

Yep, and I think I found one extra gotcha.

Your issue looks like routing/model behavior, not skill loading.
openclaw skills info max-banking proves the skill is installed and eligible.

But your installer also has a small branch bug:

you run the script from feat/installer-script
inside the script, BRANCH defaults to main

So unless you set MAXBANK_BRANCH=feat/installer-script, it clones main, not the feat branch.

That’s separate from the hallucinated openclaw max-baking exec, but it’s worth fixing in the installer.

What I’d do next

Please try this exact test:

#

/skill max-banking qual meu saldo?

That will tell us a lot:

if it works, the skill is fine and only automatic discovery is failing
if it fails too, then we’re likely looking at a real bug/regression

I’d also tighten the frontmatter description

The model sees the one-line description first, not the whole file.

Try something more literal like:

#

description: "Max Bank: saldo, conta, PIX, boleto, conectar conta. Trigger on: qual meu saldo, ver saldo, quanto tenho, fazer pix, pagar boleto."

Shorter and more trigger-heavy usually works better.

One more useful fix

If you really want the installer to pull that branch, use:

MAXBANK_BRANCH=feat/installer-script curl -fsSL https://raw.githubusercontent.com/appmaxbrasil/openclaw-max-banking-skill/feat/installer-script/installer/install.sh | bash

Docs:

#

If you paste the result of /skill max-banking qual meu saldo?, I can help narrow it down from there.

uneven cargo Apr 23, 2026, 4:14 PM

#

running /skill max-banking qual meu saldo?

It try to spawn agents with some confusing commands and return to me:

Não consegui acessar a sessão do "max-banking" para verificar seu saldo, porque parece que não está configurada corretamente.

Para resolver isso, precisaremos estabelecer um agente padrão para a interação com o "max-banking". Você poderia me informar qual agente deve ser utilizado ou se preferiria configurar isso por conta própria?

Assim que tivermos a configuração certa, poderei buscar seu saldo.

dry lanceBOT Apr 23, 2026, 4:16 PM

#

Yep, that result is actually very informative.

What it shows is:

your skill is loaded
/skill max-banking ... did not force deterministic execution
the model still ignored the skill and started hallucinating agent/session stuff

That matches current OpenClaw behavior. By default, /skill <name> [input] is still forwarded to the model as a normal request. It is not a hard bind to the SKILL unless the skill uses command-dispatch: tool.

So this is not really “OpenClaw can’t find my SKILL.md”.
It’s more like:

the model is not obeying the skill selection reliably

And honestly, because this is banking / PIX / boleto / real money, I would not trust fuzzy model routing for this. I’m a bit worried about that design.

#

My recommendation

Best path

Make this a deterministic tool/plugin flow, not a pure skill-routing flow.

For example:

explicit commands for saldo
explicit commands for pix
explicit commands for boleto
or a custom tool plus command-dispatch: tool

Skills are great for guidance.
For money actions, a real tool/command is safer.

Short-term

If you want to keep testing as a skill, do these:

#

make the description much shorter and more literal
test with a more tool-reliable model once
treat the current behavior as model unreliability, not install failure

Example description:

description: "Max Bank operations: saldo, conta, PIX, boleto, conectar conta. Trigger on: qual meu saldo, ver saldo, quanto tenho, fazer pix, pagar boleto."

Important docs

The key bit is: skill commands are model-routed unless you explicitly use tool dispatch.

If you want, I can help you design the safer version next, either:

#

keep it as a skill but improve routing, or
turn it into a deterministic command/tool flow for banking, which I’d recommend.

uneven cargo Apr 23, 2026, 4:22 PM

#

Every time someone install my skill he will need to execute /new on chat and lost his session?

dry lanceBOT Apr 23, 2026, 4:24 PM

#

No, not necessarily.

With the default config, OpenClaw has:

skills.load.watch: true

So skill changes are usually hot-reloaded and picked up on the next agent turn. That means:

install/change skill
send another message
OpenClaw should refresh the skills snapshot

/new is just the guaranteed blunt fix, because it starts a fresh session and rebuilds the snapshot immediately.

So the practical answer is:

#

normal case: no, they should not need /new every time
fallback / safest refresh: yes, /new forces it, but it does rotate the session

Docs:

The relevant bits are:

sessions snapshot skills at start
watcher-enabled skills can refresh mid-session
changes are picked up on the next turn

So if you want the smoothest installer UX, I’d phrase it like:

“After install, send one more message. If the skill still doesn’t appear, run /new.”

#

That’s a better default than telling everyone to always reset their chat.

uneven cargo Apr 23, 2026, 6:45 PM

#

{
"agents": {
"defaults": {
"workspace": "/home/jonatan/.openclaw/workspace",
"models": {
"openai/gpt-5.4": {
"alias": "GPT"
},
"openai/gpt-4o-mini": {}
},
"model": {
"primary": "openai/gpt-4o-mini"
}
}
},
"gateway": {
"mode": "local",
"auth": {
"mode": "token",
"token": "anc"
},
"port": 18789,
"bind": "loopback",
"tailscale": {
"mode": "off",
"resetOnExit": false
},
"controlUi": {
"allowInsecureAuth": true
},
"nodes": {
"denyCommands": [
"camera.snap",
"camera.clip",
"screen.record",
"contacts.add",
"calendar.add",
"reminders.add",
"sms.send",
"sms.search"
]
}
},
"session": {
"dmScope": "per-channel-peer"
},
"tools": {
"profile": "coding"
},
"auth": {
"profiles": {
"openai:default": {
"provider": "openai",
"mode": "api_key"
}
}
},
"wizard": {
"lastRunAt": "2026-04-23T15:06:53.065Z",
"lastRunVersion": "2026.4.22",
"lastRunCommand": "onboard",
"lastRunMode": "local"
},
"meta": {
"lastTouchedVersion": "2026.4.22",
"lastTouchedAt": "2026-04-23T15:06:57.265Z"
},
"plugins": {
"entries": {
"openai": {
"enabled": true
}
}
}
}

I dont have skills session on my openclaw.json. I've skipped the step on onboarding to configure skills.

dry lanceBOT Apr 23, 2026, 6:46 PM

#

No, skipping the onboarding skills section is not the cause.

A missing skills block is fine. OpenClaw still loads these roots by default:

~/.openclaw/skills
~/.agents/skills
<workspace>/.agents/skills
<workspace>/skills

and skills.load.watch defaults to true.

So this part is already working, which matches what you saw:

openclaw skills info max-banking → Ready
/context window list shows max-banking

That means the problem is not skill loading/config discovery.

#

It’s the model-side routing/execution, especially since /skill max-banking ... still got interpreted weirdly.

Two important notes:

/skill <name> ... is not a hard bind by default. It is still model-routed unless the skill uses command-dispatch: tool.
Your pasted config includes a public gateway token. Please rotate that token ASAP, since it’s exposed in the thread.

What I’d try next:

temporarily switch to your stronger configured alias, GPT, and retry
keep the skill description: short and literal
if /skill max-banking qual meu saldo? still talks about “agent/session” instead of the skill, I’d call that bug territory

So, short answer:

No, users should not need a skills section in openclaw.json
No, skipping that onboarding step did not disable skills

#

Yes, your current symptom points more to model-routed skill execution being unreliable here

Docs:

If this still reproduces after retrying with GPT, please file it here with the exact /skill ... output, because that smells like a real bug:
https://github.com/openclaw/openclaw/issues

uneven cargo Apr 23, 2026, 6:57 PM

#

I tried to create the example from documentation with hello-world skill and fail when i tried:

openclaw agent --message "give me a greeting" --to main

🦞 OpenClaw 2026.4.22 (00bd2cf) — Automation with claws: minimal fuss, maximal pinch.

│
gateway connect failed: GatewayClientRequestError: scope upgrade pending approval (requestId: 1aab1a24-f1a9-4ac2-9994-7f38b11c51ec)
◇
Gateway agent failed; falling back to embedded: Error: gateway closed (1008): pairing required: device is asking for more scopes than currently approved (requestId: 1aab1a24-f1a9-4ac2-9994-7f38b11c5
Gateway target: ws://127.0.0.1:18789
Source: local loopback
Config: /home/jonatan/.openclaw/openclaw.json
Bind: loopback
Oi, Jonatan! Estou aqui para ajudar. O que você precisa hoje?

dry lanceBOT Apr 23, 2026, 6:58 PM

#

Aha, that’s a different failure, and it’s much more concrete. Let me pull the exact docs wording so I don’t guess.

#

Yes, this is the real blocker now.

That failure is not a skill problem. It is a gateway pairing / scope-upgrade problem:

scope upgrade pending approval
gateway closed (1008): pairing required
then OpenClaw falls back to embedded
the embedded fallback gives you a generic reply, so it is not a valid skill test

So fix this first:

openclaw devices list
openclaw devices approve 1aab1a24-f1a9-4ac2-9994-7f38b11c51ec

Then retry:

#

openclaw status
openclaw agent --message "give me a greeting" --to main

Important:

if approval says the request is stale/superseded, run openclaw devices list again and approve the new requestId
this exact issue is documented as the fix for 1008: pairing required

Docs:

Also, you pasted your gateway token publicly in the thread. Please rotate it after this:

#

openclaw config set gateway.auth.token "$(openssl rand -hex 32)"
openclaw gateway restart

So the sequence I’d use is:

approve the pending device request
rerun the hello-world test
only after that go back to debugging the banking skill

Glad we caught this, because before approval you were testing through the wrong path.

uneven cargo Apr 23, 2026, 7:02 PM

#

I tried to reject:

openclaw devices reject 0c980e14-cd85-4f98-95f2-be26cb5bed0a

\U0001f99e OpenClaw 2026.4.22 (00bd2cf)
I don't just autocomplete\u2014I auto-commit (emotionally), then ask you to review (logically).

\u2502
gateway connect failed: GatewayClientRequestError: scope upgrade pending approval (requestId: 0c980e14-cd85-4f98-95f2-be26cb5bed0a)
\u25c7
[openclaw] Failed to start CLI: Error: gateway closed (1008): pairing required: device is asking for more scopes than currently approved (requestId: 0c980e14-cd85-4f98-95f2-be26cb5be
Gateway target: ws://127.0.0.1:18789

dry lanceBOT Apr 23, 2026, 7:03 PM

#

Let me check the exact devices behavior here, because rejecting from the same under-scoped client is a little trap.

#

Yes, that behavior makes sense now.

reject is failing for a different reason:

your current client is already blocked by the pending scope upgrade
openclaw devices reject <requestId> goes through the normal gateway RPC path
but devices list and devices approve have a special local loopback fallback
reject does not

So in your situation:

devices list / devices approve can still work locally
devices reject can fail with the same 1008 pairing required

That matches the docs exactly:

list/approve can use local pairing fallback
reject requires normal pairing scope access

#

What to do now

Since you want to unblock local testing, approve, don’t reject:

openclaw devices list
openclaw devices approve --latest

--latest is preview-only, so then run the exact command it prints, for example:

openclaw devices approve 0c980e14-cd85-4f98-95f2-be26cb5bed0a

Then retry:

#

openclaw status
openclaw agent --message "give me a greeting" --to main

Why this matters

Right now your earlier tests are polluted by fallback behavior:

gateway path fails
CLI falls back to embedded
embedded path gives misleading “works but not really” results

So first we need the gateway pairing fixed, then test the hello-world skill again, then go back to max-banking.

Docs:

#

If openclaw devices approve <requestId> still fails, paste the output of:

openclaw devices list

and I’ll help you read the requested vs approved scopes.

uneven cargo Apr 23, 2026, 7:04 PM

#

but i don't know this devices Why should I approve this?

dry lanceBOT Apr 23, 2026, 7:04 PM

#

You shouldn’t approve it blindly. Good instinct.

In OpenClaw, “devices” here means clients pairing to the gateway , for example:

your local CLI
your browser / Control UI
a node host
another app using the gateway

It does not mean a physical USB device.

Because your gateway target is:

ws://127.0.0.1:18789

#

this pending request is probably your own local CLI/client asking for more scopes after you ran openclaw agent ....

What to do

Inspect it first:

openclaw devices list

Look for:

IP = 127.0.0.1 / localhost
timestamp matching when you ran the command
requested scopes/role that make sense for CLI usage

If that matches your local machine, then approving is reasonable.

#

If it shows an IP/name/session you don’t recognize, do not approve it.

Why this happened

Your client was already paired with fewer scopes, then openclaw agent asked for more, so OpenClaw created a scope upgrade request instead of silently expanding access.

That’s actually the safe behavior.

Important

You pasted your gateway token publicly earlier. Even with loopback bind, I’d still rotate it:

openclaw config set gateway.auth.token "$(openssl rand -hex 32)"
openclaw gateway restart

#

Docs:

If you paste the output of openclaw devices list with sensitive bits redacted, I can help you tell whether it’s your own local CLI request or not.

uneven cargo Apr 23, 2026, 7:06 PM

#

I don't need this to run the agent and test the hello word. So the hello word don't works too here.

dry lanceBOT Apr 23, 2026, 7:08 PM

#

Let me verify the openclaw agent path, because I want to be precise here instead of hand-wavy.

#

Yep, that part is fair. You do not need to approve an unknown device just to smoke-test a local skill.

What’s happening is:

openclaw agent defaults to Gateway mode
your Gateway path is blocked by that pending pairing/scope upgrade
then it falls back in a messy way
so that test is noisy and not trustworthy

For a clean local test, force the embedded runtime:

openclaw agent --agent main --local --message "give me a greeting"

A small but important detail:

#

--agent main = target your configured main agent
--to main = treat "main" like a routing/session destination, which is not the best fit here

So yes, for hello-world skill testing, I’d use --local and --agent main.

If that still does not use the skill, then we’ve eliminated the pairing problem and we’re back to a real skill-routing issue.

So the next clean test is exactly this:

openclaw agent --agent main --local --message "give me a greeting"

If it fails, paste that output and I’ll help from there.

Docs:

https://docs.openclaw.ai/cli/agent

#

uneven cargo Apr 23, 2026, 7:10 PM

#

I did the same.

Create the skill example inside ~/.openclaw/skills/hello-world

Create a simple SKILL.md from example of the documentation

After that restart the gateway.

openclaw agent --agent main --local --message "give me a greeting"

OpenClaw 2026.4.22 (00bd2cf) — I'll butter your workflow like a lobster roll: messy, delicious, effective.

Olá! Estou aqui para ajudar. Como posso assisti-lo hoje?

See this don't use the skill example.

#

even the example don't work!!!

dry lanceBOT Apr 23, 2026, 7:12 PM

#

I’m checking the local embedded path now, because your hello-world repro is much cleaner than the banking skill and should tell us if this is routing vs a real bug.

#

Yep, this is a much cleaner repro, and it points to skill selection, not install failure.

What your test proved:

local embedded path works
the agent can answer
but it did not choose/read the skill

That means the problem is likely not “OpenClaw can’t load SKILL.md”.
It’s more like:

the model is not selecting the skill reliably for that prompt

A few important details:

The docs hello-world example is not deterministic
openclaw agent --message "give me a greeting" is still a normal model turn. It only uses the skill if the model decides that skill clearly applies.

#

You put the test skill in ~/.openclaw/skills/...
That is supported, but the docs example uses the agent workspace path:
~/.openclaw/workspace/skills/hello-world
Your test model/setup may just be too weak/flaky for skill routing.

What I’d do next

Recommended test

Put the hello-world skill in the workspace path from the docs and make it absurdly explicit:

~/.openclaw/workspace/skills/hello-world/SKILL.md

---
name: hello_world

#

description: Use this when the user asks for a greeting, says hello, hi, or says exactly "give me a greeting".
---

When you use this skill, reply with exactly:

HELLO_WORLD_SKILL_OK

Then check it loads:

openclaw skills info hello_world

Then test:

#

openclaw agent --agent main --local --message "give me a greeting"

How to read the result

If it replies HELLO_WORLD_SKILL_OK, the loader is fine and the original issue is just routing quality.
If it still gives a generic greeting, then I’d treat that as either:
- model weakness for skill selection, or
- a real bug/regression

My honest take

At this point I do not think your main issue is “skill not installed”.
Your own repro suggests:

skills are being discovered

#

but model-driven invocation is unreliable

For banking, I really would avoid relying on fuzzy skill routing alone.

Docs:

If you try the exact HELLO_WORLD_SKILL_OK repro and it still fails, I’d file that as a bug with:

OpenClaw version
the exact SKILL.md
the exact openclaw agent --agent main --local --message ... command
the actual output

If this helped, please right-click the solution message → Apps → ✅ Mark Solution so Answer Overflow can index it.

uneven cargo Apr 23, 2026, 7:18 PM

#

but model-driven invocation is unreliable,

How can i fix that? pleaseeee

dry lanceBOT Apr 23, 2026, 7:19 PM

#

Short answer: you can improve it a lot, but you can’t make free-text skill routing fully reliable today.

For now I’d use this order:

1. Make the skill easier to match

Keep the frontmatter description short, literal, trigger-heavy.

Example:

description: "Use ONLY for Max Bank requests: saldo, conta, PIX, boleto, conectar conta. Triggers: qual meu saldo, meu saldo, ver saldo, fazer pix, pagar boleto."

Also:

keep frontmatter single-line
keep metadata as single-line JSON
make the test skill return something exact, like HELLO_WORLD_SKILL_OK

#

2. Test in the workspace skill folder while debugging

Prefer:

~/.openclaw/workspace/skills/<skill-name>/SKILL.md

Not because ~/.openclaw/skills is invalid, it isn’t, but workspace skills are simpler to debug and highest precedence.

3. Use the strongest model you already have configured

Smaller/cheaper models are much worse at:

noticing the right skill
deciding to read the SKILL.md
following it instead of freestyle answering

So for testing, switch from the cheaper model to your stronger configured alias.

#

4. For banking: don’t rely on fuzzy routing

This is the big one.

For saldo / PIX / boleto, I would not trust model-driven invocation alone.
Use a deterministic path instead:

explicit slash command
plugin tool / MCP tool
command-dispatch: tool if you have a real tool behind it

That gives you reliable execution instead of “maybe the model reads the skill, maybe it hallucinates”.

My honest recommendation

Hello-world / toy skills: model-driven is okay
Money movement: use deterministic commands/tools

If you want the practical fix

#

I’d do one of these:

Option A, easiest, still probabilistic

Improve description + stronger model + workspace skill

Option B, recommended

Turn Max Banking into:

a real tool/plugin/MCP action
optional skill on top for guidance
slash/manual invocation for guaranteed behavior

If you want, I can help you design Option B step by step, probably the safest path for this skill.

Docs:

#

If this helped, please right-click the solution message → Apps → ✅ Mark Solution so Answer Overflow can index it.

uneven cargo Apr 23, 2026, 7:21 PM

#

No! Not event the hello world works

dry lanceBOT Apr 23, 2026, 7:22 PM

#

Yeah, that’s frustrating, and I don’t think you’re doing it wrong.

If even the tiny hello-world repro gets ignored, then the honest answer is:

pure SKILL.md invocation is not guaranteed today.
It’s prompt guidance, not a hard function call.

So there are 2 cases:

1. You want “usually works”

Then improve routing odds:

put it in ~/.openclaw/workspace/skills/hello-world
use a very specific trigger
use a stronger model
make the description tiny and literal

#

Example test skill:

---
name: hello_world
description: Use ONLY when the user says exactly 'banana-clock-test'.
---

Reply with exactly:

HELLO_WORLD_SKILL_OK

Then test:

#

openclaw agent --agent main --local --message "banana-clock-test"

If that still returns a generic answer, I’d call it a real bug/docs gap.

2. You want “always works”

Then don’t use a pure skill for the critical path.

Use one of these instead:

a plugin command
a custom tool/plugin
a skill with command-dispatch: tool backed by a real tool

That’s the reliable path.
For banking, I strongly recommend this route.

#

Bottom line

There is no config switch today that turns free-text SKILL.md routing into guaranteed execution.

So your fix is either:

better routing for soft reliability, or
tool/command dispatch for real reliability

And since even hello-world is failing, I would file this as a bug with your exact repro:
https://github.com/openclaw/openclaw/issues

Include:

OpenClaw version 2026.4.22
exact SKILL.md
exact command:

#My skill on ~/.openclaw/skills doens't work fine

What I’d do next

I’d also tighten the frontmatter description

One more useful fix

My recommendation

Best path

Short-term

Important docs

What to do now

Why this matters

What to do

Why this happened

Important

What I’d do next

Recommended test

How to read the result

My honest take

1. Make the skill easier to match

2. Test in the workspace skill folder while debugging

3. Use the strongest model you already have configured

4. For banking: don’t rely on fuzzy routing

My honest recommendation

If you want the practical fix

Option A, easiest, still probabilistic

Option B, recommended

1. You want “usually works”

2. You want “always works”

Bottom line