Creating Your First Skill

+15 Mana ✨
OpenClaw Creating Skills Tutorial(DOCUMENTATION)OpenClaw Skill Testing Guide(DOCUMENTATION)

Introduction

Creating a skill involves writing a SKILL.md file with proper frontmatter and clear instructions. This lesson walks through the complete process from planning to testing, using a practical example of a code review skill that analyzes pull requests and provides structured feedback.

Key Concepts

  • Skill Planning: Deciding what the skill does, who triggers it, and what it needs to run
  • Frontmatter Configuration: Setting the right metadata fields for your use case
  • Instruction Writing: Crafting clear, step-by-step instructions that produce consistent agent behavior
  • Skill Testing: Verifying the skill works as expected through invocation and iteration
  • Skill Placement: Where to put the skill directory so OpenClaw discovers it

Real World Context

Your team does code reviews on every pull request but reviewers sometimes miss important aspects like error handling, test coverage, or breaking API changes. You decide to create a skill that the agent uses to provide a structured first-pass review, catching common issues before a human reviewer looks at the code.

Deep Dive

Let us build a code review skill step by step.

Step 1: Create the Skill Directory

Skills live in the .openclaw/skills/ directory (or a custom path configured in your setup). Create a new directory for the skill:

bash
mkdir -p ~/.openclaw/skills/code-review

This creates the skill directory where the SKILL.md file and any supporting files will live.

Step 2: Write the Frontmatter

Start the SKILL.md file with the YAML frontmatter:

yaml
---
name: code-review
description: Analyzes pull request diffs and provides structured review feedback covering correctness, security, performance, and test coverage
user-invocable: true
disable-model-invocation: false
requires:
  bins: ["git", "gh"]
  env: ["GITHUB_TOKEN"]
---

This frontmatter tells OpenClaw that the skill is named code-review, can be triggered by users with /code-review, can also be used by the agent automatically, and requires git, the GitHub CLI, and a GitHub token to function. If any requirement is missing, the skill will be flagged as unavailable rather than failing at runtime.

Step 3: Write the Instructions

Below the frontmatter, write the Markdown instructions:

markdown
# Code Review Skill

When invoked, perform a structured code review:

## Gathering Context
1. Run `gh pr view --json title,body,files` to get PR metadata
2. Run `gh pr diff` to get the complete diff
3. Identify the programming languages involved

## Analysis Checklist
Review the diff against each category:

### Correctness
- Logic errors or off-by-one mistakes
- Null/undefined handling
- Edge cases not covered

### Security
- Hardcoded secrets or credentials
- SQL injection or XSS vulnerabilities
- Insufficient input validation

### Performance
- N+1 query patterns
- Unnecessary allocations in loops
- Missing indexes for new queries

### Test Coverage
- Are new functions tested?
- Are edge cases covered in tests?
- Do existing tests still pass?

## Output Format
Present findings as:
1. Summary (1-2 sentences)
2. Issues found (categorized by severity: critical, warning, suggestion)
3. Positive observations (what the PR does well)
4. Recommended actions

These instructions give the agent a deterministic workflow to follow. The gathering context section tells it what data to collect. The analysis checklist provides specific things to look for. The output format ensures consistent, readable reviews.

Step 4: Test the Skill

Invoke the skill to verify it works:

bash
# In a conversation with your agent:
/code-review

The agent will load the skill's instructions and begin following them. Observe the output and refine the instructions based on what works well and what needs adjustment.

Common Pitfalls

  • Writing ambiguous instructions: "Review the code" is too vague. Specify exactly what to look for, in what order, and how to present findings.
  • Forgetting to list requirements: If your skill needs gh but does not declare it in requires.bins, the agent may try to invoke it and fail confusingly.
  • Not testing with real data: A skill that looks good on paper may produce poor results with actual diffs. Always test with representative examples.

Best Practices

  • Start with the output format: Define what the skill's result should look like before writing the steps to produce it. Work backwards from the desired output.
  • Use explicit tool commands: Instead of "check the PR," write "Run gh pr diff to get the diff." Explicit commands produce more reliable behavior.
  • Iterate based on results: Your first version will not be perfect. Run the skill several times, note where the agent deviates from your expectations, and refine the instructions.

Summary

  • Creating a skill involves making a directory, writing SKILL.md with frontmatter and instructions, and testing
  • Frontmatter should declare all requirements (bins, env) so unavailability is detected early
  • Instructions should be explicit, step-by-step, and include a defined output format
  • Test the skill with real data and iterate on the instructions based on observed behavior
  • Place skills in ~/.openclaw/skills/ or your configured skills directory
✓ Completed