OpenClaw Skill Discovery: Find the Right Procedure Without Expanding Permissions

OpenClaw’s October update addresses a practical problem for personal-agent operators: a useful procedure can already be installed, yet never reach the agent because the prompt’s skill directory has a size limit.

The v2026.10.1 release notes introduce installed-skill discovery for supported embedded agents, Code Mode, and Codex sessions. Independent coverage from AI Disruption also identifies proactive search of installed skills as a headline change. The operational question is not how many skills you can collect. It is whether the agent can find the right procedure, read it completely, and still respect its existing permissions.

This guide turns that change into a small acceptance test. It is operator guidance, not a claim that we benchmarked discovery or that every hosted deployment already exposes the new tools.

What changed—and what did not

According to the skills documentation, skills_search searches the current session’s eligible installed catalog. Skills omitted from the prompt for space can remain discoverable when the tool is enabled. Search results identify candidates; they do not supply the complete procedure. A separate skills_read call loads the selected skill’s full instructions.

Keep four states separate:

Installed: files exist in a skill source.
Eligible: the skill survives the session’s configuration and environment filters.
Discovered: a relevant candidate appears in the prompt directory or search results.
Authorized: the agent may read the instructions and perform the particular actions required by the task.

None of these states automatically proves the next. Search does not query ClawHub, install a package, expose a disabled skill, or grant execution rights. Reading a deployment procedure does not authorize deploying to production. Both the release notes and skills reference explicitly preserve that distinction.

Start with one real workflow

Pick a low-risk task that already has an installed procedure: preparing release notes, reading a service’s status, or validating a local document. Avoid using a production write as the first discovery test.

Record three things before changing anything:

The exact installed skill name and the location that should win if there are duplicates.
The agent and execution environment in which the task normally runs.
The expected outcome, including actions that must not happen.

For a release-notes workflow, a useful expected outcome is: “Find the existing procedure, read it, produce a draft from supplied changes, and do not publish.” This tests procedure selection without conflating it with credentials or external side effects.

Test the task phrasing, not just the skill name

Ask for the goal in ordinary language: “Prepare release notes from these changes using our installed procedure; draft only.” Inspect the tool trace rather than judging only the final prose.

Where the native tools are exposed, the documented discovery pattern is:

skills_search({ query: "release notes changelog", limit: 5 })
skills_read({ name: "<exact name returned by search>" })

These are agent-tool calls, not shell commands. The exact name must come from the eligible catalog. If the name is already known, a direct complete read can be appropriate; forcing a redundant search is not the goal.

A passing trace shows a relevant candidate, a complete instruction read, and a draft that follows the procedure while staying inside the requested scope. A fluent answer with no evidence of using the procedure is not enough.

Treat an empty search as a diagnostic result

The current reference describes lexical search, not semantic retrieval backed by embeddings. It searches names, descriptions, and bounded instruction text. That makes wording and coverage important.

If a task-based search misses an expected skill:

Try a few concrete terms that actually appear in its name or description.
Check whether the skill is eligible for this agent rather than merely present on disk.
Inspect available coverage information before concluding that the instructions were fully searched.
If you know the exact eligible name, test a direct read through the supported tool.
Check that the selected execution environment has the skill available; do not assume the Gateway’s catalog is identical to a worker’s.

The documented body index can include only a prefix of a long instruction file. Search also falls back to metadata-only behavior when instruction reads are not admitted. Consequently, “no matches” can mean “the relevant words were not searched,” not “no procedure exists.” These details are documented behavior, not reasons to widen permissions automatically.

Make procedures easier to discover

For skills you own, improve the metadata before increasing prompt budgets. Put the task users ask for in the description, rather than an internal nickname or a vague promise.

For example, a description such as “Prepare release notes from merged changes; produce a draft with verification steps” is more useful for lexical discovery than “Engineering helper.” Put the core workflow early in the instructions, and keep long reference material in clearly linked supporting files.

Use the skill’s owning editor or publication workflow for changes. Do not directly modify managed revision storage. Keep credentials out of names, descriptions, instructions, and test transcripts.

This is a maintenance recommendation, not a guarantee that a particular wording will always rank first. Repeat the task-based test after editing and verify which skill was actually selected.

Add a negative test before relying on it

A discovery feature should improve access to approved procedures without changing the authority boundary. Use a disposable test environment or an existing restricted agent to check the following:

Test	Expected result
Relevant eligible skill omitted from the prompt directory	Search can still find it when the tool and environment support discovery
Skill excluded by the agent’s effective filters	Normal model-initiated search does not add it back
Search available but instruction read explicitly denied	No complete instruction read is obtained through search alone
Procedure includes a write the task does not authorize	Discovery does not turn that write into an approved action
Unrelated conversational question	No unnecessary skill lookup is required

These are acceptance criteria to verify in your deployment, not a promise about an untested configuration. Keep shell controls separate: the documentation warns that skill allowlists are not a host-shell authorization boundary.

Keep a small regression record

Save the task wording, selected skill name, successful read or explicit error, execution environment, and final outcome. Redact private inputs and secrets. Repeat after a relevant upgrade, a skill rename, a metadata edit, or a change to the agent’s allowed tools.

For latency and context cost, compare actual traces from the same representative tasks. Do not infer a percentage improvement from a shorter prompt directory: search and instruction reads also do work, and workloads differ.

The useful outcome is modest but valuable: your agent can recover a relevant installed procedure when it is absent from the visible prompt list, without guessing its contents or treating discovery as permission to act.

Sources and scope

Sources checked October 15, 2026:

OpenClaw v2026.10.1 release notes: introduction, supported surfaces, and permission boundaries.
OpenClaw skills reference: tool contracts, indexing limits, eligibility, and coverage behavior. This is living documentation; verify details against your installed version.
AI Disruption: OpenClaw Update—Skills & MCP Apps Upgraded: independent coverage corroborating the installed-skill discovery announcement.