OpenClaw Skill Not Working: Complete Install & Debug Guide 2026
The Problem: OpenClaw's skill system is what makes it infinitely extensible — you can give your agent new abilities by installing or creating skills. But when a skill fails to load, executes incorrectly, or simply doesn't seem to do anything, debugging it can feel like a mystery. This guide covers every failure mode for both community skills and custom skills you build yourself.
Skills are OpenClaw's plugin system. User @ivanfioravanti on X captured the excitement: "Finally tried my own @openclaw and I've been blown away. This is unbelievably powerful and virtually limitless, you can create your own extensions in few hours with the help of AI." And user @iamsubhrajyoti noted: "I wanted to automate some tasks from Todoist and claw was able to create a skill for it on its own, all within a Telegram chat."
What makes skills powerful also makes them complex. A skill is a JavaScript file (or a set of files) that extends OpenClaw's capabilities. When it works, your agent gains a new superpower. When it breaks, diagnosing whether the issue is in the skill code, the tool registration, the permissions, or the network requires systematic debugging.
How OpenClaw Skills Work
Before debugging, understand the skill lifecycle. Skills go through four stages before they're usable:
Install
Skill file placed in skills directory
Load
Gateway reads and validates skill file
Register
Tool is made available to the AI agent
Execute
Agent calls tool in response to a task
Failure can happen at any of these four stages. Your diagnostic approach must identify which stage broke to apply the right fix.
Step 1: Quick Skill Status Diagnostic
# List all installed skills and their status
openclaw skills list
# Output example:
# ✓ gmail-reader [loaded] Last run: 2026-03-08 08:30
# ✓ calendar-check [loaded] Last run: 2026-03-08 08:30
# ✗ todoist-sync [error] Error: API key not configured
# ⚠ weather-fetch [loaded] Last run: never
# Run the skill directly to test
openclaw skills run [skill-name]
# View skill logs
openclaw skills logs [skill-name] --tail 50
# View skill file content
openclaw skills show [skill-name]
# Run doctor for skill-specific issues
openclaw doctor --skills
Cause #1: Skill Not in the Right Directory
The most common installation failure. OpenClaw looks for skills in a specific directory within the workspace. Placing skill files anywhere else means they're silently ignored — no error, no warning, the skill just doesn't appear in the list.
# Find the correct skills directory
openclaw config get skills.directory
# Or check workspace directory:
openclaw config get workspace
# Skills go in: [workspace]/skills/
# Common default location:
ls ~/.openclaw/workspace/skills/
# Should show your .js skill files
# If the directory doesn't exist, create it:
mkdir -p ~/.openclaw/workspace/skills/
# Move skill files to correct location:
mv ~/Downloads/my-skill.js ~/.openclaw/workspace/skills/
# After moving files, reload without restart:
openclaw reload
# Verify skill is now detected:
openclaw skills list
Cause #2: Skill File Has Syntax Errors
If a skill file has JavaScript syntax errors, it will fail to load. OpenClaw logs the error internally but may not surface it obviously in the chat interface. The skill shows as [error] in the list, but without knowing where to look, the reason isn't obvious.
# Check skill loading errors in detail
openclaw logs --type skills --tail 100
# Or run skill validation directly:
openclaw skills validate [skill-name]
# Run the JavaScript file through Node to check syntax:
node --check ~/.openclaw/workspace/skills/my-skill.js
# If there are syntax errors, Node will show them here
# Common syntax errors in community skills:
# 1. Missing closing bracket } or )
# 2. Async function not properly awaited
# 3. Import/require syntax mismatch (ESM vs CommonJS)
# 4. Invalid JSON in skill metadata section
Common Skill File Structure Issues
// ❌ Wrong: Missing export
async function mySkill(params) {
return "result";
}
// ✅ Correct: Proper export
export async function mySkill(params) {
return "result";
}
// ❌ Wrong: Missing metadata
export async function mySkill(params) { ... }
// ✅ Correct: With required metadata
/** @skill
* name: My Custom Skill
* description: Does something useful
* version: 1.0.0
*/
export async function mySkill(params) { ... }
Cause #3: Missing API Keys or Environment Variables
Skills that interact with external services (Google Calendar, Todoist, Slack, etc.) require API keys. If these aren't configured, the skill loads successfully but fails every time it tries to execute. This is the most common reason a skill appears to load but does nothing.
Configure API Keys for Skills
# Method 1: Set in openclaw.json env section
{
"env": {
"GOOGLE_CALENDAR_API_KEY": "your-key-here",
"TODOIST_API_TOKEN": "your-token-here",
"OPENWEATHER_API_KEY": "your-key-here",
"SLACK_BOT_TOKEN": "xoxb-your-token-here"
}
}
# Method 2: Use openclaw config set
openclaw config set env.GOOGLE_CALENDAR_API_KEY "your-key"
# Method 3: Set system environment variables
# Add to ~/.zshrc or ~/.bashrc:
export GOOGLE_CALENDAR_API_KEY="your-key"
# Method 4: Ask OpenClaw to help you configure the skill:
"I just installed the Gmail skill but it's not working.
What API key or configuration does it need?
Walk me through setting it up."
Cause #4: VirusTotal Security Scan Blocking Skill
OpenClaw partnered with VirusTotal for skill security scanning (announced in early 2026). When you install a community skill, OpenClaw may scan it and block execution if it triggers any security warnings. This is especially common for skills that make network requests or access local system resources.
Handling Security Scan Blocks
# Check if skill is blocked by security scan
openclaw skills security [skill-name]
# View the specific security concern
openclaw skills security [skill-name] --verbose
# If you trust the skill source and want to bypass scan:
openclaw skills trust [skill-name]
# ⚠️ Only do this for skills from verified/trusted sources
# View security report for all skills
openclaw skills security --all
# Enable/disable VirusTotal scanning
openclaw config set security.virusTotal.enabled false ← Disables scanning (not recommended)
openclaw config set security.virusTotal.enabled true ← Re-enables
The VirusTotal integration is a feature, not a bug — it protects you from malicious community skills. Only bypass it for skills you fully understand and trust.
Cause #5: Node.js Version Incompatibility
OpenClaw requires Node.js 20 or higher. Skills written for newer Node features (like native fetch, newer ES modules syntax, or newer built-in APIs) will fail on older Node versions. This is a surprisingly common issue — many developers have multiple Node versions installed and OpenClaw uses the wrong one.
# Check current Node.js version
node --version
# Should be v20.x.x or higher
# Check which Node OpenClaw is using
openclaw doctor | grep -i node
# If Node is outdated, update it:
# Using nvm (recommended):
nvm install 20
nvm use 20
nvm alias default 20
# Or using Homebrew on macOS:
brew install node@20
brew link node@20
# Restart OpenClaw gateway after updating Node:
openclaw gateway stop
openclaw gateway start
Cause #6: Skill Loads but Agent Doesn't Use It
This is a trickier failure mode. The skill loads correctly, it appears in openclaw skills list with a green checkmark, but when you ask the agent to perform the skill's task, it doesn't use the skill — it either tries a different approach or says it can't do the task at all.
Why This Happens
- Skill description doesn't match your request phrasing
- Too many skills confusing the agent's tool selection
- Skill description is too vague for the model to understand when to use it
- Model prefers built-in tools over skill-based tools
How to Fix It
- Explicitly name the skill in your request
- Ask agent to list available skills first
- Improve skill description to be more specific
- Use
openclaw skills run [name]to force execution
# Tell agent explicitly which skill to use:
"Use the todoist-sync skill to fetch my incomplete tasks."
# List available skills so agent knows what's available:
"What skills do you have available? List them all."
# Or from terminal:
openclaw skills list
# Force skill execution:
openclaw skills run todoist-sync
# Improve skill discovery by updating description in the skill file:
# Open the skill file and make description more specific:
/** @skill
* name: Todoist Task Fetcher
* description: Fetches tasks from Todoist. Use when the user asks about tasks,
* todos, or wants to see their Todoist task list.
* triggers: ["todoist", "tasks", "todos", "task list"]
*/
Having OpenClaw Debug Its Own Skills
One of OpenClaw's most powerful features is its ability to debug and fix its own skills. Users discovered that you can ask the agent to diagnose why a skill isn't working and have it write a fix. This meta-capability is one of the things that amazes experienced users most.
Self-Debugging in Action
# Tell OpenClaw to debug a specific skill:
"The todoist-sync skill isn't working.
Read the skill file, check the error logs,
identify the problem, and fix it."
# Have it write a test for the skill:
"Write a test for the todoist-sync skill and run it."
# Have it update a broken skill:
"The weather-fetch skill fails with a 401 error.
Read the skill code, check what API it's calling,
and update it to use the correct authentication."
# Have it create a new version of a broken skill:
"The Gmail skill is outdated.
Create an updated version that uses the OAuth2 flow."
This approach works remarkably well. The agent reads its own skill code, understands the error, and writes a corrected version — often faster than a human developer could debug it manually.
Building Your First Custom Skill
The fastest way to create a working custom skill is to let OpenClaw write it for you. User @iamsubhrajyoti noted: "claw was able to create a skill for it on its own, all within a Telegram chat." Here's how to request a custom skill correctly to ensure it works on the first try:
Requesting Custom Skills Effectively
# ❌ Too vague (will produce a broken skill):
"Create a skill for Todoist."
# ✅ Specific enough to work:
"Create a skill called todoist-fetch-tasks that:
1. Connects to the Todoist API using env var TODOIST_API_TOKEN
2. Fetches all incomplete tasks from the Inbox project
3. Returns them as a formatted list with task name, due date, and priority
4. Should be triggered when I ask about my tasks or todos
After creating the skill, test it by running it and showing me the result."
# After skill is created, verify it's in place:
openclaw skills list
openclaw skills run todoist-fetch-tasks
Network Issues Causing Skill API Failures
Many skills make external API calls — to Google Calendar, Todoist, Slack, GitHub, or other services. These calls can fail due to network issues: DNS resolution failures, connection timeouts, or IP-based restrictions. A skill that works perfectly in one network environment may fail in another.
This is particularly relevant for users in regions where certain API providers are throttled or blocked. A skill calling the Google Calendar API from a network that throttles Google traffic will time out consistently, appearing to be a skill bug when it's actually a network issue. Routing through a stable VPN resolves this class of problem entirely.
VPN07 — Unlock Every Skill API Call
Reliable network for all your OpenClaw skill API connections
VPN07's 1000Mbps network across 70+ countries has served users reliably for over 10 years. When your OpenClaw skills call Google Calendar, Slack, GitHub, or any other API, route through VPN07 for stable, unthrottled connections — turning skill API timeouts into successful executions.
Popular Community Skills That Actually Work in 2026
The OpenClaw community has shared hundreds of skills across Discord and X.com. These are the most reliably working skills as of early 2026, confirmed by multiple users to install and run correctly:
Google Calendar Skill
Reads and creates calendar events. Requires Google Calendar API key. Most stable of all Google service skills.
Required: GOOGLE_CALENDAR_API_KEY env var
Gmail Reader Skill
Reads, searches, and drafts emails. Uses Gmail API OAuth. Popular for morning briefing automation.
Required: Gmail OAuth2 credentials
Todoist Skill
Creates, reads, and completes Todoist tasks. Simple REST API, most reliable for beginners.
Required: TODOIST_API_TOKEN env var
Weather Fetch Skill
Fetches weather data via OpenWeatherMap API. Simple skill, great for learning skill development.
Required: OPENWEATHER_API_KEY env var
GitHub Skill
Reads issues, PRs, and CI status. Used by many developers to monitor their repos via Telegram.
Required: GITHUB_TOKEN env var
RSS Reader Skill
Fetches and summarizes RSS feeds. No API key required — works out of the box with any RSS URL.
Required: Nothing — just a feed URL in your request
Skill Debug Quick Reference
| Symptom | Likely Cause | Quick Fix |
|---|---|---|
| Skill not in list | Wrong directory | mv skill.js ~/.openclaw/workspace/skills/ |
| Skill shows [error] | Syntax error or invalid metadata | node --check skill.js |
| Skill runs but fails | Missing API key | Add key to env in openclaw.json |
| Skill blocked | VirusTotal security scan | openclaw skills trust [name] |
| Agent ignores skill | Poor skill description | Name skill explicitly in your request |
| API timeout errors | Network/ISP throttling | Use VPN07 for stable connections |
Skill FAQ
Do skills run in a sandbox? Can they harm my system?
Skills run with the same permissions as the OpenClaw process (your user account). They can read/write files, make network calls, and run system commands. The VirusTotal integration scans community skills for known malicious patterns. For your own custom skills written by OpenClaw AI, review the code before trusting it — especially anything that reads or writes files outside the workspace.
Can I share my custom skills with others?
Yes! The OpenClaw community shares skills via Discord, GitHub, and X.com. Simply share the .js skill file. Remove any hardcoded API keys first — good skills use environment variables (process.env.YOUR_API_KEY) so others can set their own credentials.
How many skills can OpenClaw handle?
There's no hard limit, but practical performance degrades with too many skills. The model must understand all available tools to pick the right one — beyond ~50 skills, tool selection accuracy decreases. Group related skills into a single skill file when possible, or organize by category and load context-specific skill sets for different types of work.
Can skills trigger other skills?
Yes, through agent orchestration. One skill can pass its output as input to another by having the agent chain tool calls. Ask OpenClaw: "Fetch my GitHub issues using the github skill, then create Todoist tasks for each open issue using the todoist skill." The agent will chain both skills in sequence.