OpenClaw Skills: How to Build, Use, and Share Custom Skills

OpenClaw agents are only as useful as the actions they can perform. Out of the box, an agent with just a SOUL.md file can answer questions and hold conversations. But the real power comes from skills: modular capabilities that let agents interact with the outside world.

Skills turn a chatbot into a worker. An agent with the right skills can check your email every morning, review pull requests, sync your calendar, post Slack updates, and generate reports. All without you writing a single line of orchestration code.

This guide covers everything you need to know about OpenClaw skills: what they are, which ones come built-in, how to add them to your agent, how to build your own, and how to share them with the community.

What Are OpenClaw Skills?

A skill is a self-contained unit of functionality that an agent can call at runtime. Unlike instructions in SOUL.md (which shape how the agent thinks and responds), skills are executable code that perform real actions: read a file, call an API, send a notification, run a database query.

Each skill is defined in a skill file that lives in your agent's workspace. The file contains three things:

• Trigger: When should this skill activate? (e.g., when the user asks to "check email" or when a scheduled event fires)
• Logic: What does the skill actually do? (the code that runs)
• Output: What does the skill return to the agent? (text, data, confirmation)

Skills are registered with the OpenClaw gateway, which makes them available to any agent that has the right permissions. When an agent encounters a task that matches a skill's trigger, it invokes the skill through the gateway's function-calling interface.

This architecture means skills are reusable across agents. A "send Slack message" skill works for your PM agent, your DevOps agent, and your marketing agent. You write it once and any agent can use it.

Built-in Skills

OpenClaw ships with a core set of skills that cover the most common automation needs. These are available immediately after installation without any extra configuration.

Web Search

Lets the agent search the web and return results. Uses configurable search providers (Google, Bing, DuckDuckGo). The agent receives structured results with titles, URLs, and snippets, and can follow up by reading individual pages.

File Management

Read, write, list, and delete files on the local filesystem. Supports both absolute and relative paths (relative to the agent's workspace). Includes safeguards like confirmation prompts for destructive operations and path sandboxing to prevent agents from accessing files outside their workspace.

Shell Command Execution

Run any shell command and capture the output. This is the most flexible built-in skill because it lets agents use any CLI tool installed on the system: git, npm, docker, curl, python, and everything else. Commands run in the agent's workspace directory by default.

API Requests

Make HTTP requests (GET, POST, PUT, DELETE) to any endpoint. Supports custom headers, request bodies, and authentication. The agent can parse JSON responses and use the data in follow-up actions. This is the foundation for most third-party integrations.

Code Execution

Execute JavaScript, Python, or Bash scripts in a sandboxed environment. The agent can write code, run it, inspect the output, and iterate. Useful for data processing, calculations, and quick prototyping without leaving the agent conversation.

Browser Automation

Navigate web pages, fill forms, click buttons, and extract content using a headless browser. Built on Playwright. Requires the browser permission in SOUL.md. Useful for scraping, testing, and interacting with web apps that do not have APIs.

How to Add Skills to Your Agent

Adding a skill to an agent involves two steps: placing the skill file in the right location and declaring it in your agent's configuration.

Step 1: Understand the Workspace Structure

Every OpenClaw agent has a workspace directory. The standard layout looks like this:

~/.openclaw/agents/my-agent/
  SOUL.md           # Agent personality and instructions
  AGENTS.md         # Sub-agent definitions (optional)
  HEARTBEAT.md      # Scheduled tasks (optional)
  skills/           # Skill files go here
    web-search.js
    gmail-check.js
    slack-notify.js
  sessions/         # Conversation history
  data/             # Agent data storage

Step 2: Add the Skill File

Drop the skill file into the skills/ directory. If the directory does not exist, create it. Each skill is a single file (JavaScript or Python) that exports a specific structure.

# Copy a community skill into your agent's workspace
cp ~/downloads/gmail-morning-rollup.js \
   ~/.openclaw/agents/my-agent/skills/

# Or create one from scratch
touch ~/.openclaw/agents/my-agent/skills/my-custom-skill.js

Step 3: Register the Skill in SOUL.md

Open your agent's SOUL.md and add the skill to the skills section. This tells the gateway which skills this agent is allowed to use and how to find them.

# In SOUL.md — add a skills section
skills:
  - name: gmail-morning-rollup
    path: ./skills/gmail-morning-rollup.js
    permissions:
      - network
      - file_read

  - name: slack-notify
    path: ./skills/slack-notify.js
    permissions:
      - network

Step 4: Restart and Verify

After adding skills, restart the gateway so it picks up the new configuration. Then verify the skills are loaded.

# Restart the gateway
openclaw gateway restart

# Ask the agent to list its skills
openclaw agent --agent my-agent --message "list your skills"

# Or check via gateway directly
openclaw gateway skills list

Building Custom Skills

When the built-in skills and community skills do not cover your use case, you can build your own. A custom skill is a JavaScript or Python file that follows the OpenClaw skill specification.

The Skill File Structure

Every skill file exports a configuration object and an execution function. Here is a minimal example:

// skills/weather-check.js
module.exports = {
  name: "weather-check",
  description: "Check the current weather for a given city",
  parameters: {
    type: "object",
    properties: {
      city: {
        type: "string",
        description: "The city name to check weather for"
      }
    },
    required: ["city"]
  },
  async execute({ city }) {
    const apiKey = process.env.WEATHER_API_KEY;
    const url = `https://api.weatherapi.com/v1/current.json?key=${apiKey}&q=${city}`;

    const response = await fetch(url);
    const data = await response.json();

    return {
      city: data.location.name,
      temperature: data.current.temp_c,
      condition: data.current.condition.text,
      humidity: data.current.humidity
    };
  }
};

Step-by-Step: Build a Custom Skill

Let's walk through building a skill that monitors a GitHub repository for new issues and summarizes them.

1. Define the trigger and parameters. What input does the skill need? In this case, a repository name and optionally a time range.

// skills/github-issue-monitor.js
module.exports = {
  name: "github-issue-monitor",
  description: "Fetch recent issues from a GitHub repo and summarize them",
  parameters: {
    type: "object",
    properties: {
      repo: {
        type: "string",
        description: "Repository in owner/name format (e.g. mergisi/openclaw)"
      },
      since: {
        type: "string",
        description: "ISO date string, only fetch issues after this date"
      }
    },
    required: ["repo"]
  },

2. Write the execution logic. This is where the actual work happens.

  async execute({ repo, since }) {
    const token = process.env.GITHUB_TOKEN;
    const sinceParam = since ? `&since=${since}` : "";
    const url = `https://api.github.com/repos/${repo}/issues?state=open&sort=created&direction=desc${sinceParam}`;

    const response = await fetch(url, {
      headers: {
        "Authorization": `Bearer ${token}`,
        "Accept": "application/vnd.github.v3+json"
      }
    });

    const issues = await response.json();

    if (!Array.isArray(issues) || issues.length === 0) {
      return { count: 0, summary: "No new issues found." };
    }

    const summary = issues.map(issue => ({
      number: issue.number,
      title: issue.title,
      author: issue.user.login,
      labels: issue.labels.map(l => l.name),
      created: issue.created_at
    }));

    return {
      count: issues.length,
      repo,
      issues: summary
    };
  }
};

3. Test the skill locally. Before attaching it to an agent, verify it works on its own.

# Test the skill directly with Node
node -e "
  const skill = require('./skills/github-issue-monitor.js');
  skill.execute({ repo: 'mergisi/awesome-openclaw-agents' })
    .then(r => console.log(JSON.stringify(r, null, 2)))
    .catch(e => console.error(e));
"

4. Register it in SOUL.md and restart the gateway. Once the skill works in isolation, add it to your agent's skill list and restart.

10 Most Useful Skills

Based on community usage and the most common agent workflows, here are the 10 skills that deliver the most value.

1. Gmail Morning Rollup

Scans your inbox every morning and produces a prioritized summary. Groups emails by sender, flags urgent items, and highlights action-required messages. Pair this with a HEARTBEAT.md schedule to run automatically at 8 AM.

2. Slack Channel Notifications

Posts structured messages to Slack channels. Useful for daily standups, deployment notifications, error alerts, and progress updates. Supports Slack Block Kit formatting for rich messages with buttons and sections.

3. GitHub PR Review

Fetches open pull requests, reads the diff, and generates a code review summary. Can flag potential issues (large files, missing tests, security patterns), suggest improvements, and post review comments directly on the PR.

4. Calendar Sync

Connects to Google Calendar or Outlook and retrieves today's schedule. The agent can reference your meetings when planning tasks, block focus time, and warn you about scheduling conflicts. Read-only by default; write access requires additional permissions.

5. Database Query

Runs SQL queries against PostgreSQL, MySQL, or SQLite databases. The agent can inspect schemas, run analytical queries, and format results as tables or summaries. Includes query validation to prevent destructive operations (DROP, TRUNCATE) unless explicitly permitted.

6. Web Scraper

Extracts structured data from web pages. Goes beyond the basic web search skill by rendering JavaScript-heavy pages, handling pagination, and extracting specific elements using CSS selectors. Built on the browser automation skill.

7. File Watcher

Monitors a directory for changes and triggers actions when files are created, modified, or deleted. Useful for build pipelines, content workflows, and log monitoring. The agent can react to file changes in real time without polling.

8. PDF Generator

Converts text, Markdown, or HTML content into formatted PDF documents. Useful for generating reports, invoices, proposals, and documentation. Supports custom templates, headers, footers, and page numbering.

9. Image Analysis

Sends images to a vision model and returns descriptions, extracted text (OCR), or structured analysis. Useful for processing screenshots, receipts, diagrams, and design mockups. Works with both local files and URLs.

10. Cron Scheduler

Defines recurring tasks using cron syntax. While HEARTBEAT.md handles basic scheduling, this skill offers finer control: run a task every 15 minutes, only on weekdays, or on the first Monday of each month. The agent manages its own schedule and can adjust timing based on results.

Sharing Skills

One of the best things about the OpenClaw ecosystem is that skills are just files. There is no proprietary format, no compilation step, no vendor lock-in. If you built a useful skill, sharing it is as simple as pushing a file to GitHub.

Share via GitHub

The most common way to share skills is through GitHub repositories. Create a repository with your skill files, include a README explaining what each skill does and what environment variables it needs, and share the link.

# Example repository structure for shared skills
my-openclaw-skills/
  README.md
  skills/
    gmail-morning-rollup.js
    slack-daily-standup.js
    github-pr-review.js
  .env.example

Community Contributions

The awesome-openclaw-agents repository is the central hub for community-shared agents and skills. You can submit your skills through a pull request or open a discussion to share what you have built.

Skill Marketplace (Coming Soon)

A dedicated skill marketplace is on the OpenClaw roadmap. The plan is to let developers publish verified skills with documentation, version history, and usage stats. Until then, GitHub and the community forums are the best places to discover and share skills.

Skills vs Tools vs Integrations

These three terms come up often in OpenClaw discussions and they overlap enough to cause confusion. Here is how they differ.

Skills

Skills are agent-side capabilities. They are defined in skill files, registered with the gateway, and invoked by the agent autonomously during a conversation. The agent decides when to use a skill based on the task at hand. Skills are the highest-level abstraction and often combine multiple tools and integrations under the hood.

Tools

Tools are lower-level utilities that skills can call. A "web search" tool returns raw search results. A "summarize search results" skill uses that tool, processes the output, and returns a formatted summary. Tools do one thing. Skills orchestrate tools to accomplish a goal.

Integrations

Integrations are persistent connections to external services. A Slack integration stores your OAuth token and provides authenticated access to the Slack API. Multiple skills can use the same integration: one skill sends messages, another reads channels, a third monitors mentions. Integrations handle authentication and connection management so skills do not have to.

When to Use What

• Use a built-in skill when the task is common (file ops, web search, shell commands)
• Use an integration when you need persistent access to a third-party service (Slack, GitHub, Gmail)
• Build a custom skill when you need specific logic that combines multiple tools or integrations
• Use a tool directly when you need raw, low-level access without the skill abstraction layer

Troubleshooting Skills

When skills do not work as expected, here are the most common issues and how to debug them.

Skill Not Appearing in Agent's Skill List

• Verify the skill file exists in the skills/ directory
• Check that it is listed in SOUL.md under the skills: section
• Restart the gateway (openclaw gateway restart)
• Check gateway logs for registration errors

Skill Executes But Returns Empty or Wrong Results

• Test the skill in isolation first (node -e "require('./skill').execute(params)")
• Check that all required environment variables are set (API keys, tokens)
• Verify the external API is responding correctly (test the endpoint with curl)
• Look for unhandled errors in the skill code, especially around JSON parsing and null values

Skill Works Locally But Fails After Deployment

• Replace hard-coded paths with environment variables or relative paths
• Ensure all dependencies (npm packages, Python libraries) are installed on the target machine
• Check that the deployed environment has network access to external APIs
• Verify that the gateway process has the correct PATH and environment variables

Permission Denied Errors

If the agent reports "permission denied" when trying to use a skill, check the permissions block in SOUL.md. Each skill declares what permissions it needs, and the agent's SOUL.md must grant those permissions.

# Common permission types
permissions:
  - shell_read      # Read shell output
  - shell_write     # Execute shell commands that modify state
  - file_read       # Read files
  - file_write      # Create, modify, delete files
  - network         # Make HTTP requests, access external APIs
  - browser         # Control headless browser
  - database        # Run database queries

Rate Limiting and Timeout Issues

Skills that call external APIs can hit rate limits. Build retry logic with exponential backoff into your skill's execute function. For long-running skills, increase the gateway's timeout configuration:

# In gateway config — increase timeout for slow skills
gateway:
  skill_timeout: 60000  # 60 seconds (default is 30000)
  retry:
    max_attempts: 3
    backoff_ms: 1000

Get Started with Pre-Built Skills

Building custom skills is powerful, but you do not have to start from scratch. If you want an agent that already has a tested, working skill set out of the box, take a look at CrewClaw's agent gallery. Each agent comes pre-configured with skills for its role: DevOps agents have deployment and monitoring skills, marketing agents have content and analytics skills, PM agents have project tracking and reporting skills.

Browse over 160 ready-to-deploy agents with skills already configured and tested. Pick a role, customize the personality, and you have a working AI employee in under 60 seconds.