You installed a skill. You edited the config. You may have even written your own SKILL.md from scratch. Then you asked your agent to use it, and nothing happened. It answered from general knowledge, reached for the wrong tool, or flatly told you it “cannot do that.” Meanwhile the skill and the tool are clearly sitting right there on disk.
This is one of the most common OpenClaw frustrations, and it almost never means your skill is broken. It means the agent never saw it, or the description did not match what you asked, or a permission quietly blocked the call. Those are three different problems with three different fixes.
This guide walks the whole chain: how tools and skills actually reach your agent, how to confirm what it can see, and how to fix selection and permissions so the right tool gets used every time. By the end you will have a repeatable diagnostic you can run in about ten minutes.
How OpenClaw Actually Decides What Your Agent Can Do
Under the hood there are two separate mechanisms, and mixing them up is the main reason people get stuck.
Tools are capabilities the model can call. They are policy-filtered before every turn. The gateway assembles the list of tools allowed for that agent, channel, and session, and only that filtered list is placed into the model’s tool schema. If a tool is not in the schema, the model has no idea it exists. It will not “forget” to use it. It literally cannot see it.
Skills are not tools. A skill is a folder with a SKILL.md file that holds instructions: how to do a specific job, which tools to use, what the edge cases are. The model never receives the whole skill up front. It receives a short index containing each skill’s name, its description, and the file path. When your request matches a description, the agent reads that SKILL.md and follows it.
That design choice explains most “my agent ignores my skill” complaints. The model only picks a skill if the one-line description in the frontmatter matches the way you phrased the request. Vague descriptions lose to the model’s built-in habits every single time.
So the diagnostic order is always the same: (1) can the agent see the tool, (2) is the skill discoverable, and (3) is anything blocking the call. This is the same instinct behind fixing a slow, vague agent in long chats, which is really a context and visibility problem wearing a different mask.

Fix 1: Confirm the Tool Is Actually Visible to That Agent
Start by listing which agents exist and what each one is allowed to do. Tool access is granted per agent, so a tool that works in your main session can be invisible in a subagent or on a different channel.
The things that actually change visibility:
- Agent allowlist: only agents listed in your tool-sharing config can run tools. A brand new agent is not automatically included.
- Tool profile: a full profile exposes everything; a minimal profile exposes far less. Check the profile value before you blame the model.
- Case-sensitive names: tool ids are matched exactly.
readis notRead. - Channel capabilities: some tools only exist on certain channels, such as buttons, threads, or voice. On a plain text channel they are simply absent from the schema.
If the tool is genuinely missing, you are looking at a config problem, not a prompt problem. That is a different bug from a tool that exists but throws an error, which is covered in the tool not found fix guide.
Fix 2: Make Your Skills Discoverable
Skills live in a few standard places. Workspace skills live in your workspace skills folder, plugin skills live in the OpenClaw plugin directory, and shipped skills live under the OpenClaw install. If your SKILL.md sits anywhere else, the agent never sees it in the index.
The first two lines of that frontmatter are the whole game. name and description are what the agent sees when it decides whether to load the skill. If the description is generic, like “helps with marketing,” it will lose to the model’s default behavior on almost every request. Rewrite it as a trigger that names the situation.
Before: “Handles email.”
After: “Use when the user wants to build or edit a MailerLite email sequence, welcome flow, or subscriber segment.”
Two more rules trip people up constantly:
- One skill up front. The agent is instructed to load at most one skill before acting, so overlapping descriptions compete with each other. Make yours specific enough to win its niche.
- Version and path stability. If the skill file changes, the agent must re-read it. Stale instructions produce stale behavior, so keep the path stable and the file self-contained.
You can also disable a skill entirely in config, which removes it from the index. A skill with enabled: false is invisible to the agent even though the folder is still sitting on disk. If you want the full walkthrough on building and wiring skills, that is covered in our guide to customizing your workflow with OpenClaw skills.
Fix 3: Stop Permissions and Approvals From Blocking the Call
Sometimes the agent does pick the tool and the call is refused. That is the permissions layer doing its job. You just need to align it with what you actually want.
- Exec approvals: shell commands are gated by your exec security and ask settings. If approvals are off and no approval has been granted, the command simply does not run.
- Sandbox: a sandboxed agent cannot touch files outside its allowed paths, so a tool that works in a normal session can fail with a path error inside the sandbox.
- Filesystem policy: read and write tools are restricted to allowed roots. Writing outside them returns a denial, not a crash.
- External actions: messages, uploads, and API writes are intentionally separated from internal work. If a tool “does nothing,” check whether it is sitting on a confirmation.
The fix is not to switch everything off. Narrow it instead: allow the specific paths and commands the skill needs, keep approvals on for the destructive ones, and hand the agent a scoped credential instead of your master one.
If your hosting is the bottleneck: Kinsta keeps your site safe with automatic daily backups and one-click restore, so a bad update or a hack is a rollback, not a rebuild. Their support is top tier, and 24/7 live chat is staffed by WordPress engineers who will help fix the actual problem with you, so you are not stuck waiting on your developer to reply. Plans start at $35 per month.
Common Mistakes to Avoid
- Describing the topic instead of the trigger. The model needs to know when to load the skill, not just what the skill is about.
- Re-implementing tools inside skills. Do not rebuild “read a file” in a skill. Point the skill at the tool that already exists.
- Assuming a subagent inherits everything. Subagents get a filtered tool set. Re-check visibility per agent, every time.
- Editing a skill and not re-reading it. Version drift means the session keeps using the old instructions until the file is re-read.
- Turning off approvals to “make it work.” That removes the safety net for every future destructive command too.
- Testing once. Tool selection is probabilistic. Run the same prompt three times before you declare victory.

Verify It Worked
Run the same request three ways and watch which one fails.
- Ask plainly, the way a real user would. The agent should pick the skill or tool without you naming it.
- Ask explicitly, naming the skill (“use the mailerlite skill”). If this works but step one fails, it is a description problem, not a permissions problem.
- Inspect the transcript. If the tool never appears in the call, it is invisible (Fix 1). If it appears and errors, it is permissions (Fix 3).
If step one and step two both fail, the tool is not in the schema at all. Go back to Fix 1 and check the agent allowlist.
Read our step-by-step guide to building and customizing your own skills so your agent does exactly what you need.
See Our GuideFrequently Asked Questions
Usually the one-line description in the skill’s frontmatter does not match how you phrased the request. The agent only sees each skill’s name, description, and path, so a vague description loses to the model’s default behavior. Rewrite it as a trigger that names the situation, then re-test the same prompt three times.
A tool is a capability the model can call, like reading a file or sending a message, and it only exists if the gateway includes it in the filtered tool schema for that turn. A skill is a set of instructions in a SKILL.md file that tells the agent how to do a job. Skills guide behavior, tools do the work.
Tool access is granted per agent. Subagents get a filtered tool set, and only agents on the sharing allowlist can run tools. Check the agent list and the tool profile for that specific agent instead of assuming it inherits the main session’s access.
Look at the transcript. If the tool never appears in the call list, it is invisible to the model and you have a discovery problem. If it appears and returns an error or a denial, the model saw it and something blocked the call, so it is a permissions or sandbox issue.
Editing the body of a SKILL.md does not require a restart, because the agent re-reads the file when it triggers. Changing which skills are enabled in config, or adding a new skill folder, does need a reload so the index is rebuilt.
Final Thoughts
If your agent is ignoring a skill or a tool, resist the urge to rewrite the skill from scratch. Nine times out of ten the skill is fine, and the failure sits one layer up: the tool was filtered out of the schema, or the description never matched your request, or a permission refused the call. Check visibility first, then discoverability, then permissions, in that order.
Fix the description so it names the trigger, keep the skill path stable, and grant narrow access instead of wide access. Do that and your agent stops guessing and starts reaching for exactly the right tool.
Next step: audit one skill you actually rely on. Read its first two frontmatter lines out loud and ask whether they truly match how you would phrase the request. If they do not, that is a two-minute fix with an outsized payoff.

