How to Build Your First OpenClaw Skill

Building a custom OpenClaw skill lets you teach your AI coding agent exactly how you want it to behave. Whether you want to enforce code style, add framework-specific knowledge, or create reusable workflows, this guide walks you through the entire process.

Prerequisites

Before you start, make sure you have OpenClaw installed and working in your terminal. You should also be familiar with basic markdown syntax, since OpenClaw skills are written in markdown with structured frontmatter.

Step 1: Plan Your Skill

Start by identifying a specific behavior you want your agent to follow. Good skills are focused and opinionated. Instead of creating a generic "JavaScript skill," create a "React Testing Library with Vitest" skill that covers a specific combination.

Defining the Scope

Write down three to five concrete examples of what your skill should change about the agent's behavior. For instance:

• Always use screen.getByRole instead of screen.getByTestId
• Prefer userEvent over fireEvent
• Structure tests with describe/it blocks using specific naming conventions

Step 2: Create the Skill File

Create a new directory for your skill and add a skill.md file:

mkdir my-testing-skill
cd my-testing-skill
touch skill.md

Add the frontmatter header with metadata:

---
name: react-testing-vitest
description: React Testing Library patterns with Vitest
version: 1.0.0
author: your-github-username
tags: [react, testing, vitest]
---

Step 3: Write the Instructions

Below the frontmatter, write clear and specific instructions. Use headings to organize sections. Include code examples that demonstrate the preferred patterns.

Writing Effective Instructions

Be direct and specific. Instead of writing "use good testing practices," write "always query elements by their accessible role using screen.getByRole. Never use test IDs unless no accessible role exists."

Include both positive examples (what to do) and negative examples (what to avoid). The agent learns faster when it sees the contrast.

Step 4: Test Locally

Install your skill locally to test it before publishing:

openclaw skill install ./my-testing-skill

Run your agent and ask it to perform tasks covered by your skill. Verify that the agent follows your instructions. Iterate on the wording if the agent misinterprets anything.

Debugging Tips

If the agent ignores your skill instructions, check that:

• The frontmatter is valid YAML
• The file is properly installed (run openclaw skill list)
• Your instructions are clear and unambiguous
• You do not have conflicting skills installed

Step 5: Publish Your Skill

Once your skill works well locally, publish it to the OpenClaw community. Push your skill directory to a public GitHub repository, then submit it to the OpenClaw Bazaar for listing.

Skill Quality Checklist

Before publishing, verify your skill meets these standards:

• Clear, focused scope documented in the description
• At least three code examples showing preferred patterns
• No conflicting or contradictory instructions
• Tested with at least two different types of prompts

Next Steps

Browse existing skills on the OpenClaw Bazaar for inspiration. Study how popular skills structure their instructions. Join the OpenClaw community to get feedback on your skill before publishing.

Building OpenClaw skills is one of the most impactful ways to contribute to the open-source AI tooling ecosystem. Every skill you publish helps other developers write better code with their AI agents.

Browse the Skills Directory

Find the right skill for your workflow. The OpenClaw Bazaar skills directory has over 2,300 community-rated skills — searchable, sortable, and free to install.

Browse Skills →

Go Pro

Pro sellers get featured placement in the directory, install analytics, and priority support. If you are serious about reaching the OpenClaw community, Pro is the way to go.

Learn about Pro →