Skills Quickstart: Install, Use, and Configure

One-sentence goal: install your first OpenClaw Skill into your Gateway, confirm it loads correctly, and complete the basic gating and allowlist configuration.

Prerequisites

• You have finished the prerequisite page "Advanced Handbook: Skills and Security Hardening", and your Gateway is running normally (OpenClaw 2.0 means v2026.8.1 and above; Node requires 24.16.0+ or 26.1.0+).
• You know where your workspace directory and state directory are.
• At least one chat channel (Discord, Telegram, etc.) is connected to Claw, for convenient verification via conversation.
• Build the concept first: a Skill is not a code plugin but a markdown instruction file that teaches an agent how and when to use tools. Each skill is a directory containing SKILL.md (YAML frontmatter + markdown body). OpenClaw loads built-in skills and local overrides, and filters them at load time based on environment, configuration, and whether binaries exist.

Follow Along

Step 1: Install a Skill

Browse and pick a community skill from ClawHub and install it with the CLI, or place the skill directory locally.

openclaw skills install @owner/<slug>

By default it installs into skills/ of the current workspace; add --global to install into the shared <state-dir>/skills/.

Local method: copy the entire skill directory (it must contain SKILL.md) into a load directory, for example the workspace-level <workspace>/skills/, or the managed <state-dir>/skills/.

Expected result: the skill directory appears at the target location and is scanned and loaded after the Gateway reloads.

Step 2: Verify Loading and Priority

Use the CLI to view the list of loaded skills and confirm the new skill appears; when same-name conflicts occur, troubleshoot from high to low using the priority table.

openclaw skills list

When same-name skills appear in multiple locations, the higher-priority source wins:

Priority	Source	Path
1 (highest)	Workspace skills	<workspace>/skills
2	Project agent skills	<workspace>/.agents/skills
3	Personal agent skills	~/.agents/skills (default state only)
4	Managed/local skills	<state-dir>/skills
5	Workshop skills	<state-dir>/agents/<agentId>/agent/workshop-skills
6	Built-in / Custodian skills	shipped with the installation package; Custodian skills are only visible to the system agent specified by agents.defaults.systemAgent.agentId
7 (lowest)	Extra directories	specified by skills.* configuration

Expected result: the new skill appears in the list; when same-name conflicts occur, the higher-priority source wins.

Step 3: Configure Gating and the Allowlist

In the configuration file (by default ~/.openclaw/openclaw.json), skill gating and environment injection go in the skills.* section, and the agent allowlist (restricting which agents can use which skills) goes in the agents.* section. Save after editing, then run openclaw gateway restart to reload the Gateway.

skills.* Common keys: skills.entries.<技能名>.enabled (toggle for gating an individual skill), skills.entries.<技能名>.env and apiKey (environment injection), skills.load.extraDirs (additional load directories), skills.install.* (install behavior), skills.allowBundled (built-in skill whitelist). Allowlist rules: omitting agents.defaults.skills means no restriction; agents.entries.<agentId>.skills is that agent's final skill set (a full replacement, not a merge), and [] means no skills.

Expected result: gated skills no longer apply to all agents; agents within the allowlist work normally.

Verify

Say something in the chat channel that can trigger the skill, and see whether Claw calls tools and executes the flow as described in SKILL.md. Then temporarily rename the skill directory and reload to confirm the skill disappears from the list—proving the load really comes from the directory you placed rather than a built-in skill with the same name.

Common Pitfalls

• Same-name skills silently overridden: the higher-priority source wins outright with no error. When troubleshooting, work through the priority table above level by level.
• A skill just won't load: OpenClaw filters at load time based on environment, configuration, and whether binaries exist. If a command-line tool the skill depends on isn't installed, the skill may simply be filtered out. Use openclaw skills check to distinguish the three kinds of problems: inventory/readiness/visibility.
• Directory placed at the wrong level: ~/.agents/skills only serves as a personal agent skill source under the default state; personal library skills on a shared Gateway are selected by identity and revision, not by scanning each user's files.
• Writing a Skill like a program: it is just markdown instructions that teach an agent to use tools. If you want Claw to grow skills on its own, check out Skill Workshop—starting from 2.0 it collects proposals/checks/decisions, and from v2026.10.5 it supports version history and undo.

Next Lesson

Once the skill runs successfully, move on to "Write Your Own Skill: SKILL.md and Publishing to ClawHub" to write a SKILL.md from scratch and publish it to ClawHub. Further reading: "Skill Workshop: Letting Claw Learn Skills on Its Own" and "MCP Integration: Giving Claw an External Toolbox".