How to Debug OpenClaw Skills That Aren't Working

You installed a skill, ran a prompt, and the agent ignored your instructions. Or it followed some instructions but not others. Or it worked yesterday but broke after you added a new skill. Sound familiar?

Debugging OpenClaw skills is a skill in itself. Unlike traditional software where you get stack traces and error messages, agent skills fail silently — the agent just does something different from what you expected. This guide gives you a systematic approach to figuring out what went wrong and how to fix it.

Start With the Basics

Before diving into advanced debugging, rule out the simple stuff:

Is the Skill Actually Installed?

openclaw skill list

Check that the skill you expect to see is in the output. If it is missing, it was not installed or was removed at some point. Reinstall it:

openclaw skill install <skill-name>

Is the Skill Active?

A skill can be installed but not active. Check your openclaw.config.toml:

[skills]
active = [
  "typescript-strict-mode",
  "next-app-router-expert",
  # Is your skill listed here?
]

If the skill is installed in .openclaw/skills/ but not listed in active, the agent will not load it. Add it to the array.

Is the Skill Version Compatible?

Skills can break after an OpenClaw CLI update. Check compatibility:

openclaw skill info <skill-name>

Output:

next-app-router-expert v1.8.2
───────────────────────────────
Compatible with: openclaw >=2.2.0 <3.0.0
Your version:    openclaw 2.4.1
Status:          ✓ Compatible
Last updated:    2026-02-15

If the status shows incompatible, update the skill:

openclaw skill update <skill-name>

Use Verbose Mode

Verbose mode is your most powerful debugging tool. It shows exactly what the agent receives, including the merged skill instructions:

openclaw run --verbose

In verbose mode, the agent logs:

1. Skill loading order — which skills are loaded and in what sequence
2. Merged instructions — the complete instruction set sent to the agent
3. Conflict resolutions — any conflicts that were automatically resolved
4. Token usage — how much of the context window each skill consumes

Reading Verbose Output

Look for these common issues in verbose output:

Skill was loaded but instructions were truncated:

[WARN] Skill "comprehensive-api-patterns" truncated: 18,400 tokens exceeds
       per-skill limit of 12,000 tokens. Instructions after line 342 were dropped.

This means the skill's instructions are too long and the tail end got cut off. If the behavior you need is defined late in the skill file, it was never sent to the agent. Solutions: ask the skill author to trim it, or increase the per-skill token limit in your config:

[agent]
max_skill_tokens = 20000

Skill was overridden by another skill:

[INFO] Conflict resolved: "export-style"
       Winner: security-best-practices (priority 10)
       Loser:  next-app-router-expert (priority 8)

If the losing skill's behavior is what you actually wanted, adjust priorities or add an explicit override.

Skill was loaded but the agent did not follow instructions:

This is the trickiest case. The instructions were sent, no conflicts exist, but the agent does its own thing. This usually means the instructions are too vague or the agent's general training overrides them. More on this below.

Test Skills in Isolation

When multiple skills interact, it is hard to tell which one is causing problems. Isolate the suspect:

openclaw run --skills-only <skill-name>

This starts the agent with only the specified skill loaded. No other skills, no priority conflicts, no merged instructions — just the one skill you are debugging.

Run the same prompt that produced unexpected behavior:

openclaw run --skills-only next-app-router-expert
> Create a login page with a form

If the skill works correctly in isolation, the problem is an interaction with another skill. If it still misbehaves in isolation, the problem is in the skill itself.

Bisecting Skill Issues

If isolation does not reveal the problem, use a binary search approach:

1. List all your active skills
2. Disable half of them
3. Test the prompt
4. If the issue persists, the problem is in the enabled half
5. If the issue disappears, the problem is in the disabled half
6. Repeat until you find the problematic skill

# Temporarily override active skills from the CLI
openclaw run --skills "skill-a,skill-b,skill-c"
# Test... still broken? Problem is in a, b, or c
openclaw run --skills "skill-a,skill-b"
# Test... works now? Problem was skill-c

This bisection method is faster than testing each skill individually when you have many active skills.

Check for Conflicts

The conflict checker shows known and potential conflicts between your active skills:

openclaw skill conflicts --check --verbose

Detailed output:

CONFLICT ANALYSIS
─────────────────

Detected conflicts: 3

1. RESOLVED: Export style
   security-best-practices: "Use named exports"
   next-app-router-expert: "Use default exports for pages"
   → Winner: next-app-router-expert (context-aware: app/ directory only)

2. RESOLVED: Error handling
   error-handling-patterns: "Use custom error classes"
   express-api-patterns: "Use express error middleware"
   → Winner: error-handling-patterns (priority 9 > 6)

3. UNRESOLVED: Testing approach
   vitest-testing-patterns: "Mock external dependencies"
   integration-testing-skill: "Use real service connections"
   → Action needed: Set explicit override in config

Unresolved conflicts mean the agent gets contradictory instructions with no clear winner. It will pick one arbitrarily (usually based on which instruction appears later in the merged prompt). Fix these with explicit overrides:

[skills.overrides]
"testing-approach" = "vitest-testing-patterns"

Common Failure Patterns

Pattern 1: Skill Works for Simple Prompts, Fails for Complex Ones

The agent's context window has limits. Complex prompts eat into the space available for skill instructions. If your prompt plus all skill instructions exceed the context limit, skills get silently trimmed.

Check context usage:

openclaw run --verbose --dry-run --prompt "Your complex prompt here"
# Look for: [INFO] Context usage: 87,400 / 100,000 tokens

If you are near the limit, reduce active skills for complex tasks or increase max_context_tokens.

Pattern 2: Skill Worked Before Adding a New Skill

Classic conflict issue. The new skill introduced instructions that override or contradict the existing skill. Run the conflict checker and compare the verbose output before and after adding the new skill.

Pattern 3: Skill Works on First Prompt, Degrades Over Session

Long conversations dilute skill instructions. As the conversation history grows, the agent pays less attention to the system-level instructions from skills. Two solutions:

1. Start fresh sessions for important tasks: openclaw run --new-session
2. Reinforce critical skill instructions by referencing them in your prompts: "Following the security patterns from my skills, review this code"

Pattern 4: Skill Instructions Are Too Vague

If a skill says "write clean code," the agent interprets that however it wants. Effective skill instructions are specific and actionable. Compare:

Vague (will be ignored):

Write clean, maintainable code.

Specific (will be followed):

Every function must have a JSDoc comment with @param and @returns tags.
Functions longer than 30 lines must be split into smaller functions.
Use early returns instead of nested if-else blocks.

If you are using a community skill with vague instructions, consider forking it and making the instructions more precise.

Pattern 5: Skill Defines Rules the Agent Cannot Enforce

Some instructions ask the agent to do things it cannot verify at generation time. For example, "ensure all queries use database indexes" requires knowledge of the database schema that may not be in context. The agent will try its best but cannot guarantee compliance.

Check whether your skill's expectations are realistic given what information the agent has access to.

The Debugging Checklist

When a skill is not working, run through this checklist:

# 1. Verify installation
openclaw skill list

# 2. Verify it is active in config
cat openclaw.config.toml

# 3. Check compatibility
openclaw skill info <skill-name>

# 4. Run conflict check
openclaw skill conflicts --check

# 5. Test in isolation
openclaw run --skills-only <skill-name>

# 6. Check verbose output
openclaw run --verbose --dry-run --prompt "Test prompt"

# 7. Check context usage
# (visible in verbose output)

Most skill issues resolve by step 4. If you get to step 6 and the instructions look correct but the agent still misbehaves, the issue is likely instruction quality — the skill needs clearer, more specific instructions.

Skill debugging gets faster with practice. Once you understand the resolution pipeline and the common failure patterns, most issues take under five minutes to diagnose. The tools are there — verbose mode, isolation testing, conflict checking — you just need to build the habit of reaching for them.

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 →

Built a Skill? List It on the Bazaar

If you have built a skill that others would find useful, publish it on the Bazaar. Reach thousands of developers and get feedback from the community.

Learn how to publish →