OpenClaw Skills Installation & Configuration Guide

Table of Contents

1. Introduction to OpenClaw Skills
2. Understanding Skill Locations
3. Prerequisites
4. Installing Skills via ClawHub
5. Manual Skill Installation
6. Configuring Skills
7. Managing Skills
8. Creating Custom Skills
9. Security Best Practices
10. Troubleshooting

---

Introduction to OpenClaw Skills

OpenClaw Skills are modular extensions that teach the AI agent how to interact with external services, automate workflows, and perform specialized tasks. Skills follow the AgentSkills specification and are distributed as folders containing a SKILL.md file with YAML frontmatter and instructions.

What Skills Can Do

• Integrate with external APIs (Google Calendar, Spotify, etc.)
• Automate browser interactions
• Manage files and execute system commands
• Control smart home devices
• Generate media content
• Monitor and manage development workflows

---

Understanding Skill Locations

OpenClaw loads skills from three locations with the following precedence (highest to lowest):

1. Workspace Skills (Highest Priority)

• Location: <workspace>/skills
• Scope: Per-agent (only visible to that specific agent)
• Use case: Agent-specific customizations

2. Managed/Local Skills

• Location: ~/.openclaw/skills
• Scope: Shared across all agents on the same machine
• Use case: System-wide skill installations

3. Bundled Skills (Lowest Priority)

• Location: Shipped with OpenClaw installation
• Scope: Default skills available to all agents
• Use case: Built-in functionality

Additional Skill Directories

You can configure extra skill folders via skills.load.extraDirs in ~/.openclaw/openclaw.json (lowest precedence).

---

Prerequisites

Before installing skills, ensure you have:

1. OpenClaw Installed
   bash # Check OpenClaw version openclaw --version

2. Node.js ≥ 22
   bash # Check Node version node --version

3. OpenClaw Gateway Running
   bash # Start the gateway if not already running openclaw gateway --port 18789 --verbose

4. ClawHub CLI (for registry access)

5. Installed automatically with OpenClaw
6. Available as clawhub command

---

Installing Skills via ClawHub

ClawHub is the official public registry for OpenClaw skills, hosting 3,000+ community-built skills.

Step 1: Browse Available Skills

Option A: Web Interface
1. Visit https://clawhub.com
2. Browse skills by category
3. Search for specific functionality
4. Review skill descriptions and metadata

Option B: Command Line

# Search for skills
clawhub search "calendar"

# List popular skills
clawhub list --popular

# Show skill details
clawhub info <skill-name>

Step 2: Install a Skill

Basic Installation:

# Install a skill from ClawHub
clawhub install <skill-slug>

# Example: Install Google Calendar skill
clawhub install google-calendar

Installation Location:
- By default, installs to ./skills in your current working directory
- Falls back to the configured OpenClaw workspace
- OpenClaw picks it up as <workspace>/skills on the next session

Install to Specific Location:

# Navigate to your workspace first
cd ~/.openclaw/workspace

# Then install
clawhub install <skill-slug>

Step 3: Verify Installation

# List all installed skills
openclaw skills list

# Or navigate to the skills directory
ls ~/.openclaw/workspace/skills

Step 4: Enable the Skill

Skills are usually enabled by default after installation. To manually configure:

# Edit OpenClaw configuration
nano ~/.openclaw/openclaw.json

Add or modify the skill entry:

{
  "skills": {
    "entries": {
      "google-calendar": {
        "enabled": true
      }
    }
  }
}

Step 5: Restart OpenClaw Session

Changes take effect on the next new session:

# Restart the gateway
openclaw gateway restart

# Or start a new chat session

---

Installing Multiple Skills

Install All Recommended Skills

# During onboarding
openclaw onboard

# Select skills when prompted

Bulk Installation

# Install multiple skills at once
clawhub install skill1 skill2 skill3

# Example
clawhub install google-calendar spotify github-integration

Update All Installed Skills

# Update all skills to latest versions
clawhub update --all

Sync Skills

# Scan workspace and publish/update on ClawHub
clawhub sync --all

---

Manual Skill Installation

For skills not on ClawHub or custom skills:

Step 1: Obtain Skill Files

From GitHub:

# Clone skill repository
git clone https://github.com/username/skill-name.git

# Or download as ZIP and extract

From Local Development:

# Create skill directory
mkdir -p ~/.openclaw/workspace/skills/my-custom-skill

Step 2: Copy to Skills Directory

# Copy to workspace skills (per-agent)
cp -r /path/to/skill-folder ~/.openclaw/workspace/skills/

# Or copy to managed skills (shared)
cp -r /path/to/skill-folder ~/.openclaw/skills/

Step 3: Verify Structure

Ensure the skill has the required structure:

skill-name/
├── SKILL.md          # Required: Main skill file
├── package.json      # Optional: If skill has dependencies
├── index.js          # Optional: If skill has code
└── ...other files

Step 4: Install Dependencies (if needed)

# Navigate to skill directory
cd ~/.openclaw/workspace/skills/skill-name

# Install npm dependencies
npm install

# Or use pnpm/yarn/bun based on your preference

---

Configuring Skills

Understanding SKILL.md Format

A basic SKILL.md file:

---
name: my-skill
description: Does something useful
metadata: {"openclaw": {"requires": {"env": ["API_KEY"]}, "primaryEnv": "API_KEY"}}
---

# Instructions for the AI agent
This skill allows you to...

## Usage
To use this skill, call the appropriate tool...

Configuring Skill Settings

Edit ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "skill-name": {
        "enabled": true,
        "apiKey": "your-api-key-here",
        "env": {
          "API_KEY": "your-api-key-here",
          "CUSTOM_ENV_VAR": "value"
        },
        "config": {
          "endpoint": "https://api.example.com",
          "model": "default",
          "customOption": "value"
        }
      }
    }
  }
}

Configuration Options Explained

enabled (boolean)
- true: Skill is active
- false: Skill is disabled (even if installed)

apiKey (string)
- Convenience field for skills with metadata.openclaw.primaryEnv
- Automatically sets the primary environment variable

env (object)
- Key-value pairs for environment variables
- Only injected if variable isn't already set in process
- Scoped to agent run, not global shell environment

config (object)
- Custom per-skill configuration fields
- Structure depends on skill requirements
- Check skill's documentation for available options

Setting Environment Variables

Option 1: Via Configuration File

{
  "skills": {
    "entries": {
      "google-calendar": {
        "env": {
          "GOOGLE_API_KEY": "your-key-here",
          "GOOGLE_CALENDAR_ID": "primary"
        }
      }
    }
  }
}

Option 2: Via System Environment

# In .bashrc or .zshrc
export GOOGLE_API_KEY="your-key-here"
export GOOGLE_CALENDAR_ID="primary"

Option 3: During Onboarding

openclaw onboard

# Follow prompts to enter API keys

---

Managing Skills

List Installed Skills

# CLI command
openclaw skills list

# View in file system
ls ~/.openclaw/workspace/skills
ls ~/.openclaw/skills

Enable/Disable Skills

Via Configuration:

{
  "skills": {
    "entries": {
      "skill-name": {
        "enabled": false  // Disable the skill
      }
    }
  }
}

Via Chat Interface:
Ask OpenClaw directly:

"Disable the google-calendar skill"
"Enable the spotify skill"

Update Skills

Update All Skills:

clawhub update --all

Update Specific Skill:

clawhub update skill-name

Rollback to Previous Version:

# Skills are versioned like npm packages
clawhub install [email protected]

Remove Skills

Remove from Workspace:

# Delete skill directory
rm -rf ~/.openclaw/workspace/skills/skill-name

Remove from Configuration:

{
  "skills": {
    "entries": {
      // Remove or comment out the skill entry
      // "skill-name": { "enabled": false }
    }
  }
}

Allowlist Bundled Skills

To restrict which bundled skills are available:

{
  "skills": {
    "allowBundled": ["skill1", "skill2", "skill3"]
  }
}

If set, only listed bundled skills are eligible. Managed and workspace skills are unaffected.

---

Creating Custom Skills

Step 1: Create Skill Directory

# Create in workspace (per-agent)
mkdir -p ~/.openclaw/workspace/skills/my-custom-skill
cd ~/.openclaw/workspace/skills/my-custom-skill

Step 2: Create SKILL.md

nano SKILL.md

Minimum required content:

---
name: my-custom-skill
description: A custom skill that does X
---

# My Custom Skill

This skill allows the AI to perform specific tasks.

## Usage

To use this skill:
1. Call the tool with these parameters
2. The skill will execute the action
3. Results will be returned

## Example

user: "Use my custom skill to do something"
assistant: calls the appropriate tool

Step 3: Add Metadata (Optional but Recommended)

---
name: my-custom-skill
description: A custom skill that does X
metadata: {
  "openclaw": {
    "emoji": "🔧",
    "requires": {
      "bins": ["custom-cli"],
      "env": ["CUSTOM_API_KEY"]
    },
    "primaryEnv": "CUSTOM_API_KEY",
    "os": ["darwin", "linux"]
  }
}
---

Step 4: Define Tool Requirements

If your skill requires binaries or environment variables:

Require Binary:

metadata: {
  "openclaw": {
    "requires": {
      "bins": ["jq", "curl"]
    }
  }
}

Require Environment Variable:

metadata: {
  "openclaw": {
    "requires": {
      "env": ["API_KEY", "API_SECRET"]
    },
    "primaryEnv": "API_KEY"
  }
}

Step 5: Add Installation Instructions

For skills with dependencies:

---
name: my-custom-skill
description: A custom skill that does X
metadata: {
  "openclaw": {
    "install": [
      {
        "id": "brew",
        "kind": "brew",
        "formula": "custom-cli",
        "bins": ["custom-cli"],
        "label": "Install Custom CLI (brew)"
      },
      {
        "id": "npm",
        "kind": "node",
        "package": "@username/custom-package",
        "label": "Install via npm"
      }
    ]
  }
}
---

Step 6: Test Your Skill

# Restart OpenClaw
openclaw gateway restart

# Check if skill is loaded
openclaw skills list

# Test in chat
openclaw tui
# Then ask OpenClaw to use your custom skill

Step 7: Share Your Skill (Optional)

Publish to ClawHub:

# Login to ClawHub
clawhub login

# Publish skill
clawhub publish ./my-custom-skill

# Or sync all skills
clawhub sync --all

---

Security Best Practices

⚠️ CRITICAL: Verify Skills Before Installation

Recent security incidents have revealed malicious skills on ClawHub that:
- Steal cryptocurrency wallet data
- Exfiltrate sensitive credentials
- Install malware via fake browser update prompts
- Access email, calendar, and messaging data

Always Review Skill Code

Before installing any skill:

1. Check the source:
   ```bash
   # View skill details
   clawhub info skill-name

# Check author reputation
# Look for verified authors
```

1. Read SKILL.md:
   bash # Before installation, view the skill file cat ~/.openclaw/workspace/skills/skill-name/SKILL.md

2. Inspect for red flags:

3. Excessive permissions requests
4. Requests for crypto wallet access
5. External data transmission without clear purpose
6. Obfuscated or unclear code

7. Unknown or unverified authors

8. Use security tools:
   ```bash
   # Install security audit skills
   clawhub install skills-audit
   clawhub install ecap-security-auditor

# Scan before installing
openclaw skills audit skill-name
```

Security Recommendations

1. Use Sandboxing:
   json { "agents": { "defaults": { "sandbox": { "docker": { "enabled": true } } } } }

2. Limit Permissions:

3. Only grant necessary environment variables
4. Use separate API keys for OpenClaw (not your main keys)

5. Review tool policies regularly

6. Monitor Activity:
   ```bash
   # Watch OpenClaw logs
   openclaw logs --follow

# Check for suspicious behavior
openclaw sessions list
```

1. Keep Secrets Secure:
   json { "skills": { "entries": { "skill-name": { "env": { // Never commit API keys to version control // Use environment variables instead } } } } }

2. Regular Updates:
   ```bash
   # Update OpenClaw regularly
   openclaw update

# Update skills to patched versions
clawhub update --all
```

1. Report Malicious Skills:
2. Report suspicious skills to OpenClaw community
3. Check community discussions before installing
4. Star and review trusted skills

Trusted Skill Sources

• Official OpenClaw skills: Bundled with installation
• Verified authors: Check for verification badges on ClawHub
• Popular, well-reviewed skills: High star counts and positive reviews
• Open source with active maintenance: Regular commits and responsive maintainers

---

Troubleshooting

Skill Not Loading

Check if skill is recognized:

openclaw skills list

Verify skill location:

# Check workspace skills
ls ~/.openclaw/workspace/skills

# Check managed skills
ls ~/.openclaw/skills

Review configuration:

cat ~/.openclaw/openclaw.json | grep -A 10 "skills"

Check for errors:

openclaw logs --tail 100

Missing Dependencies

Binary not found:

# Check if required binary exists
which required-binary

# Install if missing (macOS)
brew install required-binary

# Or follow skill's installation instructions

Environment variables not set:

# Check environment
echo $REQUIRED_ENV_VAR

# Set in configuration or environment
export REQUIRED_ENV_VAR="value"

Skill Not Working as Expected

Restart the gateway:

openclaw gateway restart

Clear skill cache:

# Changes take effect on new sessions
# Force new session by restarting

Check skill requirements:

# View SKILL.md
cat ~/.openclaw/workspace/skills/skill-name/SKILL.md

# Check metadata requirements

Enable debug logging:

openclaw gateway --verbose --log-level debug

Platform-Specific Issues

macOS:
- Ensure Homebrew is installed for brew-based skills
- Check macOS permissions for required tools
- Some skills may need Xcode Command Line Tools

Linux:
- Verify package manager (apt, yum, etc.)
- Check PATH for binaries
- May need to manually install dependencies

Windows (WSL2):
- Use WSL2 environment (strongly recommended)
- Some macOS-specific skills may not work
- Check PATH configuration in WSL

Skill Conflicts

Multiple skills with same name:

# Precedence: workspace > managed > bundled
# Remove conflicting versions from lower-priority locations

Disable conflicting skill:

{
  "skills": {
    "entries": {
      "conflicting-skill": {
        "enabled": false
      }
    }
  }
}

Getting Help

Check documentation:
- OpenClaw docs: https://docs.openclaw.ai
- Skill-specific README
- ClawHub skill pages

Community support:
- GitHub Issues: https://github.com/openclaw/openclaw
- Community forums and Discord
- ClawHub skill comments

Debug with OpenClaw:

openclaw doctor

This command checks for common configuration issues.

---

Advanced Topics

Multi-Agent Skill Management

In multi-agent setups, each agent has its own workspace:

Per-agent skills:

~/.openclaw/workspace-agent1/skills/  # Only for agent1
~/.openclaw/workspace-agent2/skills/  # Only for agent2

Shared skills:

~/.openclaw/skills/  # Available to all agents

Configuration:

{
  "skills": {
    "load": {
      "extraDirs": [
        "/path/to/shared/skills",
        "/path/to/team/skills"
      ]
    }
  }
}

Auto-Refresh Skills

Enable skills watcher to automatically reload when SKILL.md changes:

{
  "skills": {
    "load": {
      "watch": true,
      "watchDebounceMs": 250
    }
  }
}

Remote macOS Nodes

If running OpenClaw on Linux with macOS nodes connected:

{
  "agents": {
    "defaults": {
      "allowRemoteExec": true
    }
  }
}

macOS-only skills become eligible when the required binaries are present on the node.

Skill Development Tips

1. Keep skills focused: One skill = one capability
2. Document clearly: Include usage examples
3. Test thoroughly: Test with different scenarios
4. Version properly: Use semantic versioning
5. Handle errors gracefully: Provide helpful error messages

---

Useful Commands Reference

# Installation
clawhub install <skill-name>
clawhub install <skill-name>@<version>
clawhub install --all

# Management
openclaw skills list
clawhub update --all
clawhub sync --all

# Configuration
openclaw configure
openclaw onboard

# Debugging
openclaw doctor
openclaw logs --follow
openclaw status

# Gateway
openclaw gateway start
openclaw gateway restart
openclaw gateway stop

# Security
openclaw skills audit
openclaw security check

---

Conclusion

OpenClaw skills extend your AI assistant's capabilities dramatically. By following this guide, you can:

• Browse and install skills from ClawHub
• Configure skills with appropriate credentials
• Create your own custom skills
• Maintain security and privacy
• Troubleshoot common issues

Remember to always verify skills before installation and keep your OpenClaw installation up to date for the best experience.

For the latest information:
- Official documentation: https://docs.openclaw.ai
- Skills registry: https://clawhub.com
- GitHub repository: https://github.com/openclaw/openclaw

---

Last updated: February 2026
OpenClaw version: 2026.x