Skill-Based Commands

+15 Mana ✨
OpenClaw Skills Guide(DOCUMENTATION)OpenClaw Command Configuration(DOCUMENTATION)

Introduction

Beyond built-in commands, OpenClaw supports custom commands defined as skills. Skills are markdown files with YAML frontmatter that can be invoked by users as slash commands. The user-invocable frontmatter flag makes a skill available as a command, while command-dispatch and command-tool provide advanced invocation patterns. This lesson covers how to create and configure skill-based commands.

Key Concepts

  • user-invocable: A frontmatter flag that makes a skill available as a slash command to users
  • command-dispatch: A mechanism that routes custom commands to specific skill handlers based on the command name
  • command-tool: A frontmatter field that enables direct tool invocation when the command is used
  • Skill File: A markdown file with YAML frontmatter that defines the command's behavior and instructions
  • Frontmatter Configuration: The YAML block at the top of a skill file that controls invocation behavior

Real World Context

An engineering team creates a /deploy command that their developers can use in any chat channel to trigger a deployment pipeline. The skill file defines what the agent should do when /deploy is invoked: verify the user has permission, check that tests pass, and then execute the deployment. New team members can start deploying on day one by just typing /deploy staging without knowing the underlying pipeline details.

Deep Dive

Creating a User-Invocable Skill

A skill becomes a slash command when the user-invocable flag is set:

yaml
---
user-invocable: true
name: deploy
description: Deploy the application to a specified environment
---

# Deploy Command

When the user invokes /deploy, perform the following steps:

1. Verify the user has deployment permissions
2. Check that all tests pass on the current branch
3. Execute the deployment to the specified environment
4. Report the deployment status back to the user

This skill file, saved in the agent's skills directory, registers /deploy as an available command. When a user types /deploy staging, the agent receives the command and follows the instructions in the skill file.

Command Dispatch

Command dispatch routes commands to specific skill handlers:

yaml
---
user-invocable: true
name: ops
command-dispatch:
  deploy: ./skills/deploy.md
  rollback: ./skills/rollback.md
  status: ./skills/status.md
---

# Operations Commands

This skill dispatches to specialized handlers based on the subcommand.

With this configuration, /ops deploy routes to the deploy skill, /ops rollback routes to the rollback skill, and /ops status routes to the status skill. This creates a command hierarchy similar to CLI tools like git commit or kubectl apply.

Command Tool Integration

The command-tool frontmatter enables direct tool invocation:

yaml
---
user-invocable: true
name: health
command-tool: health-checker
---

# Health Check Command

When invoked, directly call the health-checker tool with the provided arguments.

When a user types /health production, the agent directly invokes the health-checker tool with "production" as the argument, bypassing the normal reasoning step. This is faster and cheaper for commands that map directly to a single tool call.

Skill File Location

Skill files are stored in the agent's skills directory:

bash
~/.openclaw/agents/my-agent/agent/skills/
  deploy.md
  rollback.md
  status.md
  health.md

Each file in this directory is automatically discovered and registered. The name field in the frontmatter determines the slash command name.

Common Pitfalls

  • Forgetting the user-invocable flag: Without this flag, the skill exists but is not available as a slash command. Users will get a "command not found" error.
  • Creating conflicting command names: If a skill name matches a built-in command, the built-in takes precedence. Choose unique names for custom commands.
  • Not providing clear instructions in the skill body: The agent follows the markdown instructions literally. Vague instructions produce inconsistent results.

Best Practices

  • Name commands intuitively so users can discover them without consulting documentation.
  • Include usage examples in the skill body so the agent can provide help when the user invokes the command without arguments.
  • Use command-dispatch for related commands to create clean command hierarchies.

Summary

  • The user-invocable frontmatter flag makes a skill available as a slash command
  • command-dispatch routes subcommands to specialized skill handlers
  • command-tool enables direct tool invocation for performance-critical commands
  • Skill files are markdown with YAML frontmatter, stored in the agent's skills directory
  • Always set user-invocable: true and provide clear instructions in the skill body
✓ Completed