<!-- source: https://deepwiki.com/openclaw/openclaw/5.2-skills-system -->

# Skills System

- docs/cli/plugins.md
- docs/cli/skills.md
- docs/plugins/community.md
- docs/plugins/manage-plugins.md
- docs/prose.md
- docs/tools/creating-skills.md
- docs/tools/plugin.md
- docs/tools/skills-config.md
- docs/tools/skills.md
- packages/gateway-protocol/src/schema/agents-models-skills.ts
- src/cli/skills-cli.ts
- src/cli/skills-cli.workshop.test.ts
- src/commands/doctor/shared/missing-configured-plugin-install.test.ts
- src/commands/doctor/shared/missing-configured-plugin-install.ts
- src/commands/doctor/shared/release-configured-plugin-installs.test.ts
- src/commands/doctor/shared/release-configured-plugin-installs.ts
- src/commands/doctor/shared/update-phase.test.ts
- src/commands/doctor/shared/update-phase.ts
- src/commands/onboarding-plugin-install.test.ts
- src/commands/onboarding-plugin-install.ts
- src/gateway/server-methods/skills.clawhub.test.ts
- src/gateway/server-methods/skills.proposals.test.ts
- src/gateway/server-methods/skills.test-helpers.ts
- src/gateway/server-methods/skills.ts
- src/plugins/clawhub-error-codes.ts
- src/plugins/clawhub.test.ts
- src/plugins/clawhub.ts
- src/plugins/update.test.ts
- src/plugins/update.ts
- src/skills/workshop/service.test.ts
- src/skills/workshop/service.ts
- src/skills/workshop/store.ts
- src/skills/workshop/types.ts

The Skills System in OpenClaw extends agent capabilities by providing modular instruction sets and tool definitions packaged as directory-based "skills". Each skill defines how an agent should use specific binaries, APIs, or local scripts, and includes metadata for environment injection, dependency checking, and automated installation.

## SKILL.md Format and Metadata

A skill is organized as a directory containing a `SKILL.md` file. This file mixes YAML frontmatter for configuration with Markdown for rich instructions provided to the agent [src/skills/workshop/service.test.ts:110-111].

### Technical Specification

OpenClaw implements the **AgentSkills.io** specification. The parser extracts frontmatter values to ensure compatibility with the embedded Pi agent runtime and deterministic prompt construction.

The YAML frontmatter defines essential skill metadata:

### Requirement Evaluation

OpenClaw verifies skill eligibility through requirement evaluation logic. This process ensures the agent only attempts to use skills that are functionally supported by the current environment.

- Binary Availability : Required tools must exist on the system PATH.
- Configuration Paths : Specific features (like API keys) must be active in the global openclaw.json [docs/tools/skills.md:119-120] .
- Environment Variables : Skills can require specific variables to be present in the execution context [src/skills/workshop/service.test.ts:142-142] .

**Sources:** [src/skills/workshop/service.test.ts:110-112], [src/skills/workshop/service.test.ts:142-154], [docs/tools/skills.md:11-15].

## Skill Installation and Sources

OpenClaw supports skills from multiple tiers. Higher-priority sources override lower ones if names collide. The system resolves the canonical entries for a session based on a defined precedence hierarchy [docs/tools/skills.md:32-35].

### Locations and Precedence

OpenClaw loads skills from these sources, highest precedence first [docs/tools/skills.md:37-45]:

### Bundled Skills and Allowlists

Repo-level bundled skills provide baseline functionality but are subject to security and visibility controls:

- Allowlists : Agent configurations can restrict which skills are visible using an allowlist in openclaw.json [docs/tools/skills.md:83-96] .
- Plugin Skills : Plugins can also ship skills, which load at a low precedence level similar to extra directories [docs/tools/skills.md:110-115] .

### Natural Language to Code Entity Space: Installation

The following diagram maps high-level installation concepts to specific code entities.

Title: Skill Installation and Lifecycle Flow

```

```

**Sources:** [docs/tools/skills.md:32-45], [docs/tools/skills.md:83-96], [src/gateway/server-methods/skills.ts:40-40], [src/skills/lifecycle/clawhub.ts:18-23], [src/commands/doctor/shared/missing-configured-plugin-install.ts:172-172].

## Skill Workshop

The Skill Workshop is a proposal-based system that allows agents to suggest new skills or updates to existing ones. This acts as a staging area where human operators can review, revise, or reject changes before they are applied to the active skill directories [docs/tools/skills.md:124-130].

### Technical Implementation

The workshop is managed by the `SkillWorkshopService`, which handles the lifecycle of `SkillProposal` records stored in the OpenClaw state directory [src/skills/workshop/service.ts:78-80].

- Proposal Creation : Agents or users create proposals via proposeCreateSkill or proposeUpdateSkill [src/skills/workshop/service.test.ts:49-53] .
- Support Files : Proposals can include auxiliary files (scripts, templates) stored in a managed supportFiles directory [src/skills/workshop/store.ts:153-155] .
- Application : When a proposal is applied via applySkillProposal , the service writes the SKILL.md and support files to the target workspace, effectively "installing" the skill [src/skills/workshop/service.test.ts:104-107] .

### Natural Language to Code Entity Space: Workshop Flow

This diagram maps the workshop lifecycle from proposal to active skill.

Title: Skill Workshop Proposal Lifecycle

```

```

**Sources:** [src/skills/workshop/service.ts:47-62], [src/skills/workshop/service.test.ts:47-66], [src/skills/workshop/store.ts:95-101], [src/skills/workshop/store.ts:103-115].

## Skill Execution and Prompt Injection

The bridge from static files to live execution involves discovery and status reporting. The `buildWorkspaceSkillStatus` function aggregates all available skills and determines which are "eligible" based on environment checks [src/skills/discovery/status.ts:33-33].

### Runtime Refresh and Lifecycle

The system monitors skill directories for changes. The `bumpSkillsSnapshotVersion` function is called whenever skills are modified (e.g., after applying a workshop proposal), signaling the agent runtime to refresh its capability index [src/skills/workshop/service.ts:12-12].

### Workspace Skills vs Managed Skills

OpenClaw supports multi-agent setups where skills can be either global or isolated. Workspace-specific skills allow repository-level control over agent workflows [docs/tools/skills.md:64-67].

### Implementation Overview Diagram

Title: Skills System Implementation Overview

```

```

**Sources:** [src/skills/discovery/status.ts:33-33], [src/skills/workshop/service.ts:104-107], [docs/tools/skills.md:37-45], [src/gateway/server-methods/skills.ts:146-157].
