Configuring Skill Triggers, Tools, and Instructions

Skill Frontmatter Deep Dive

The YAML frontmatter in SKILL.md controls how your skill loads, triggers, and operates. Understanding these options unlocks advanced skill behavior.

Triggers

Triggers determine when a skill activates:

triggers:
  - "translate"
  - "convert to"
  - regex: "translate .+ to .+"

Trigger Types

• Keyword: Simple string matching
• Phrase: Multi-word exact match
• Regex: Pattern matching for complex triggers
• Always: Skill is always active (use sparingly)

Tools

Tools define what actions the skill can perform:

tools:
  - read          # Read files
  - write         # Write files
  - edit          # Edit files
  - web_search    # Search the web
  - web_fetch     # Fetch web pages
  - shell         # Execute commands
  - browser       # Web automation
  - apply_patch   # Apply code patches
  - canvas        # Visual rendering

Tool Permissions

Each tool has a security implication:

• read — Safe, read-only file access
• write/edit — Can modify files
• shell — Can execute any command
• browser — Can interact with websites

Only request tools your skill actually needs.

Environment Variables

env:
  API_KEY: required         # Must be provided
  TIMEOUT: "30"             # Default value
  DEBUG: optional           # May or may not be set

Platform Requirements

platforms: [macos, linux]          # OS restrictions
requires: [ffmpeg, chromium]       # Binary dependencies
node_version: ">=20"               # Node.js version

Skill Metadata

name: my-awesome-skill
description: One-line description for registry
version: 1.0.0
author: Your Name
tags: [productivity, automation]

Advanced: Multi-Step Instructions

Write instructions as numbered steps with clear decision points:

1. Parse the user's request to identify the target language
2. If the target language is unclear, ask for clarification
3. Use web_search to verify any technical terms
4. Perform the translation
5. Format the result as:
   - Original text
   - Translated text
   - Notes on any ambiguous translations

Testing Skills

After creating or modifying a skill:

1. Reload skills: openclaw skills reload
2. Test with a matching trigger message
3. Verify the correct tools are being used
4. Check the output format matches your instructions