openclaw-skills-doctor

Audit the skills OpenClaw loads: the per-step token tax, shadowed duplicates, broken references and budget overruns - then get a measured plan to fix them.

OpenClaw injects every eligible skill into the system prompt as a compact XML block: roughly 97 characters plus name, description and location per skill, paid on every model step. This tool measures that cost, tells you which definition actually wins, and can trim or hide the expensive ones.

A thin, focused wrapper around opencode-skills-doctor that knows OpenClaw's skill roots, precedence, openclaw.json, its MCP registry and the bundled skill.

Quick start

npx -y openclaw-skills-doctor check          # findings + per-step token cost
npx -y openclaw-skills-doctor plan           # exact savings: trim and/or hide
npx -y openclaw-skills-doctor doctor         # paths, roots, install state
npx -y openclaw-skills-doctor check --html openclaw-report.html --open

Nothing to configure: the wrapper resolves the state dir and workspace the same way OpenClaw does.

Related MCP server: whats-loaded-mcp

What it audits

OpenClaw file-backed skill roots, highest precedence first:

The wrapper hands those roots to the core auditor in exactly this order, so the winning definition in a shadowing report matches what OpenClaw actually loads. Other agents' global roots (Claude, OpenCode, Grok, Cursor, Kimi, Hermes) are skipped by default; pass --include-other-agents to audit them too.

Install the integration

npx -y openclaw-skills-doctor install

That does two things and is idempotent:

1. saves the MCP server definition mcp.servers.skills-doctor in ~/.openclaw/openclaw.json - through openclaw mcp add when the CLI is installed, otherwise by patching the config directly (the previous file is backed up as openclaw.json.bak-<timestamp>);

2. installs the bundled openclaw-skills-doctor skill into <workspace>/skills/openclaw-skills-doctor.

npx -y openclaw-skills-doctor install --dry-run   # show what would change
npx -y openclaw-skills-doctor uninstall           # remove both again
openclaw mcp doctor skills-doctor --probe         # verify the server connects

Restart the Gateway (or run openclaw mcp reload) so the tool appears. MCP tools are namespaced per server, so the agent calls skills-doctor__skills_doctor.

Manual MCP setup

If you prefer to wire it yourself:

openclaw mcp add skills-doctor \
  --command npx \
  --arg -y \
  --arg opencode-skills-doctor \
  --arg mcp

or in ~/.openclaw/openclaw.json:

{
  mcp: {
    servers: {
      "skills-doctor": {
        command: "npx",
        args: ["-y", "opencode-skills-doctor", "mcp"],
      },
    },
  },
}

Paths it resolves

Override any of them with --state-dir <dir>, --workspace <dir>, --home <dir>.

Commands

Core flags work as usual: --json, --budget, --lang en|zh, --dry-run, --strict, --html [file], --no-global.

Fixing what it finds

npx -y openclaw-skills-doctor plan             # measure first
npx -y openclaw-skills-doctor fix --dry-run    # see what would be archived
npx -y openclaw-skills-doctor fix              # archive shadowed duplicates (reversible)
npx -y openclaw-skills-doctor fix --hide legacy-skill

fix only archives definitions that never load, moving them to .skills-doctor-archive/<timestamp>/ inside the same skill root. --hide adds metadata.opencode/autoinvoke: false, which keeps the skill loadable through an explicit @id reference while removing it from the model-facing list.

Safety

• check, plan, scan and doctor are read-only and offline (no network, no LLM).

• install/uninstall back up openclaw.json before rewriting it; the CLI path leaves the file alone entirely.

• uninstall only removes a bundled skill whose SKILL.md still declares name: openclaw-skills-doctor.

• Config parsing understands JSON with comments and trailing commas. A file that uses other JSON5-only syntax (unquoted keys, single quotes) is reported, never rewritten - use openclaw mcp add/set/unset there instead.

• It is not a sandbox: it audits configuration and files, it does not constrain what the agent can do.

Development

npm install
npm test        # 19 tests

Requires Node >= 20. MIT.

Changelog · 中文说明 · Core reference