My OpenClaw agent was useful for chatting. Then I added my first skill and it shifted from “a chatbot” to “something that actually does things.” This guide walks you through building a custom skill from scratch. By the end, you’ll have a working tool that your agent can call on demand. It is the single best way to make your AI feel like a real assistant. You don’t need a complex framework or a build step. Just a folder and a simple Markdown file.
What do I need to get started with OpenClaw?
You need the latest version of OpenClaw and a working agent. Make sure you have Node.js installed on your machine.
openclaw --version # Should be v2026.3.8+What is actually inside an OpenClaw skill folder?
An OpenClaw skill is just a directory in your ~/.openclaw/skills/ folder. It only needs two things to work.
- SKILL.md: This holds the instructions and metadata. It’s the “brain” of the skill.
- scripts/: This is where your actual code lives. It’s usually a simple JavaScript file.
How do I build a basic weather tool?
Let’s build a skill that fetches the current temperature for any city.
The Scenario: You’re planning a weekend hike. You ask your agent “Should I bring a raincoat?” Without a weather skill, the agent might just guess based on the season. With the skill, it hits a live API, sees a 70% chance of rain in your specific zip code, and tells you “Yes, grab the gear.”
Create your SKILL.md first. The description is what the AI reads to decide when to call the tool.
---
name: get-weather
description: Get weather for a city. Use for rain or temp questions.
user-invocable: false
---
## Input
city: string (e.g. "Mumbai")
## Call
/skill get-weather --city "<city name>"How do I make sure my script actually works?
Don’t wait for the agent to fail. Test your script manually in the terminal.
node ~/.openclaw/skills/get-weather/scripts/run.js --city "Mumbai"If it returns a clean JSON object, you’re ready to go. If it crashes, fix the bug before you plug it into the AI.
How do I “plug” the skill into my agent?
Open your agent’s config.yaml. Add the name of your skill to the skills list.
skills:
- get-weatherRestart your agent to apply the changes. Now, when you ask about the weather, the agent will call your script automatically.
Can I trigger skills manually with a slash command?
Yes. Set user-invocable: true in your SKILL.md to enable slash commands.
The Scenario: You’ve been working all day and your brain is fried. You need to write a status update for your team. Instead of digging through five different chat logs, you just type
/standup. The agent scans its memory of what you did today and spits out a perfectly formatted bulleted list in three seconds.
How do I keep my database tools safe?
Some skills need sensitive information like a database path. You can “gate” these tools so they only appear when a specific environment variable is set.
metadata:
openclaw:
requires:
env: ["PROJECT_DB_PATH"]What do all these YAML fields actually do?
- name: The unique ID for your skill.
- description: The “instruction manual” for the AI.
- user-invocable: Whether you can run it manually with
/. - requires.env: The variables needed for the skill to run.
How do I write a description that the AI actually understands?
The description is the most important part of the skill. If it’s too vague, the AI will get confused.
- Bad: “Gets information.”
- Good: “Get current weather for a city. Use for rain, temp, or clothing advice. Do NOT use for history.”
Be specific about what the tool does and what it doesn’t do.
Why isn’t my agent using the new skill?
If things aren’t working, check these three things.
- Naming: Does the folder name match the name in the
SKILL.md? - Restart: Did you run
openclaw restartafter changing the config? - Logs: Check the terminal for errors when the agent tries to call the tool.
What should I build next?
- Persistent facts: Agent Skills with Memory: Persisting State Between Chats
- Real-world actions: Build a GitHub Issue Creator Skill for Your AI Agent
- Master the basics: What Are Agent Skills? AI Tools Explained Simply
