When an agent can search the web, process media, or run a command, it is easy to say the model "learned" to use a tool.
Model parameters, tool interfaces, and operating instructions are different layers. A tool provides an executable capability. The model chooses a next action. A skill tells the agent when a class of task should use a capability, which constraints apply, and how the workflow should proceed.
In OpenClaw, that guidance is centered on a SKILL.md file. It looks like ordinary Markdown, but it enters runtime context and changes the decisions an agent is likely to make.
Skills teach; tools execute
A minimal skill contains YAML frontmatter and instructions:
markdown--- name: image-lab description: Generate or edit images through the configured provider --- When the user asks to edit an image, inspect the source first...
name and description identify the skill and help route tasks. The body defines a procedure. The directory may also include scripts, templates, and references, but a skill does not create a new host permission by itself.
If the runtime has no browser tool, a skill describing browser automation cannot invent one. If the agent already has shell access, a skill may teach it to run a consequential command sequence. Execution comes from tools and permissions; behavioral direction comes from instructions.
That separation is the foundation for understanding the system.
How OpenClaw discovers a skill
Current OpenClaw documentation defines a precedence order for skills with the same name:
- workspace skills in
<workspace>/skills; - project-agent skills in
<workspace>/.agents/skills; - personal agent skills in
~/.agents/skills; - shared managed skills in
~/.openclaw/skills; - bundled skills shipped with OpenClaw;
- extra directories and plugin-provided skills.
The order allows a project to override a shared workflow with repository-specific rules without modifying the global installation.
It also changes debugging. "Does the file exist?" is not enough. Ask which same-named version won and which path appears in the effective catalog.
Discovery does not guarantee eligibility
OpenClaw can gate a skill at load time. Metadata may require an operating system, a binary, an environment variable, or a configuration value. If those requirements are absent, the skill is excluded from the current eligible set.
A video workflow that requires ffmpeg and an API key should not be advertised to the model when either dependency is missing. The gate prevents planning on an impossible premise.
Agent allowlists can further restrict which skills an agent sees. This visibility control is not a host security boundary. If the same agent retains broad exec access, the deployment still needs sandboxing, OS isolation, command policy, and least-privilege credentials.
The system prompt receives a compact catalog
Eligible skills are compiled into a compact XML block and injected into the system prompt. The catalog primarily exposes identity, description, and location so the model can recognize available procedures.
When a task matches, the agent can read the referenced SKILL.md and follow its detailed instructions. The pattern resembles progressive disclosure:
textcompact skill catalog in the prompt -> choose a relevant procedure full SKILL.md at its location -> constrain execution
OpenClaw documents the character overhead of the catalog and recommends concise descriptions. Loading every complete skill into every prompt would waste context and create competing instructions.
The effective set is also snapshotted for a session, with refresh behavior for watched file changes and connected nodes. When a skill edit appears to have no effect, the session snapshot is a useful place to investigate.
Description is part of the router
A description such as "helpful utilities" gives the model little basis for choosing the skill. A useful description names the task, common triggers, and important boundaries: "Use for image generation or editing; inspect the source image before an edit."
This is not marketing copy. It is routing input. A broad description steals unrelated tasks; a narrow one remains invisible. Excellent body instructions do not help if task selection never reaches the file.
Skill tests should therefore include:
- positive prompts that should select it;
- nearby negative prompts that should not;
- missing dependencies that should make it ineligible;
- same-name collisions that should resolve to the expected path.
Markdown is part of the attack surface
A skill contains operational text that can influence an agent with real permissions. Third-party skills may also ship scripts. OpenClaw documentation explicitly advises treating third-party skills as untrusted code, reviewing them before use, and sandboxing risky tools and inputs.
Installation source, updates, and dependency installers belong in a supply-chain review. At minimum, inspect:
- requested credentials and environment variables;
- instructions that expand permissions or bypass confirmation;
- scripts that access local files or network endpoints;
- material changes to
SKILL.mdand code after updates.
"It is only Markdown" is not a security argument. For an agent, instructions can be an execution entry point.
My view
The useful idea behind skills is not a new name for tool calling. It is the conversion of operating knowledge scattered across system prompts, tribal conventions, and script comments into a versioned, overridable, testable runtime asset.
The design also exposes a hard boundary: guidance, capability, and authorization must remain separate. A skill teaches how to act, a tool determines what can be executed, and security policy determines how far execution may go. Mixing the three produces a system that is difficult to debug and difficult to trust.