openclaw-skills-doctor

Audit the skills OpenClaw loads: per-step token cost, shadowed duplicates, broken references.
Then get a measured plan to trim or hide the expensive ones.

English · 简体中文 · Changelog · Privacy

Runs 100% locally. No telemetry, no account, no uploads — your skills, configuration and files never leave your machine. See Privacy.

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.

Three ways to run it — CLI, MCP server, or the native OpenClaw plugin (a skills_doctor tool + /skills-doctor command). All of them share the same audit core, so the numbers always match.

Contents

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.

Or install the companion skill from ClawHub:

openclaw skills install @wangyuchen5110/skills-doctor

Example output

$ npx -y openclaw-skills-doctor doctor
openclaw-skills-doctor doctor
  cli:        /usr/local/bin/openclaw
  state dir:  /home/you/.openclaw
  workspace:  /home/you/.openclaw/workspace
  config:     /home/you/.openclaw/openclaw.json

  skill roots:
    + /home/you/.openclaw/workspace/skills
    - /home/you/.openclaw/workspace/.agents/skills
    - /home/you/.agents/skills
    + /home/you/.openclaw/skills

  mcp entry:  saved
  bundled skill: installed
  native plugin: installed + enabled
  plugin dir: /home/you/.openclaw/extensions/openclaw-skills-doctor

Privacy: local-only, no data collection

Everything runs on your machine. No telemetry, no analytics, no account, and nothing is uploaded - not your skills, configuration or files.

openclaw.json can contain channel or provider credentials. It is parsed locally only to find the entries this tool owns; values are never transmitted, printed or copied into a report. Reports contain file paths and skill descriptions, never file bodies. check, plan, scan and doctor work with the network offline.

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.

How it works

Every measurement is local and deterministic: the same skill files produce the same numbers, so the report is safe to diff in CI.

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 by patching the config directly, with a timestamped backup (openclaw.json.bak-<timestamp>) and an atomic write. It never spawns the openclaw CLI, so it also works while the Gateway is running;
2. installs the bundled openclaw-skills-doctor skill into <workspace>/skills/openclaw-skills-doctor.

npx -y openclaw-skills-doctor install --mcp-only     # just the MCP entry
npx -y openclaw-skills-doctor install --skill-only   # just the bundled skill
npx -y openclaw-skills-doctor install --plugin       # also the native plugin
npx -y openclaw-skills-doctor install --dry-run      # show what would change
npx -y openclaw-skills-doctor uninstall              # remove what install added
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.

Native plugin (optional)

install --plugin copies the package into <state-dir>/extensions/openclaw-skills-doctor and sets plugins.entries["openclaw-skills-doctor"].enabled = true. The plugin adds:

• a skills_doctor tool that returns a compact report (top findings, budget line, next step) instead of the full markdown - tool results are paid in the model context too;
• a /skills-doctor command that prints the same report directly.

openclaw plugins inspect openclaw-skills-doctor --runtime --json  # verify the load

Prefer a managed install for anything beyond local experiments:

openclaw plugins install clawhub:openclaw-skills-doctor   # from ClawHub
openclaw plugins install ./openclaw-skills-doctor         # from this checkout

The ClawHub release passed the automated security audit (v0.3.4).

The plugin API is experimental; pin your OpenClaw version and re-run openclaw plugins inspect ... --runtime after upgrades. This repository ships plain JavaScript with no build step (no TypeScript, no TypeBox), so the plugin entry is the same code the tests exercise.

Manual MCP setup

If you prefer to wire the MCP server yourself:

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

or in ~/.openclaw/openclaw.json:

{
  mcp: {
    servers: {
      "skills-doctor": {
        command: "npx",
        args: ["-y", "opencode-skills-doctor@0.9.4", "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

• Local-only: no telemetry, no backend, nothing leaves the machine; the only optional network call is the core CLI's daily npm version check, which you can disable.
• check, plan, scan and doctor are read-only and offline (no network, no LLM).
• install/uninstall back up openclaw.json before rewriting it, preserve its existing permission bits (credentials files are usually 0600), write atomically, and never spawn a child process. If the atomic replace fails the write fails closed: nothing is written and the original file stays intact.
• uninstall only removes a bundled skill when its SKILL.md was read successfully and still declares name: openclaw-skills-doctor; otherwise it leaves the directory in place with a warning.
• 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                  # 27 tests
npm run plugin:validate   # offline manifest/entry/metadata consistency

Requires Node >= 20. MIT.

Changelog · 中文说明 · Core reference