Find the skill that actually wins, the trigger that overlaps, and the risky instruction that should not stay hidden.

• Why People Install It
• Quick Proof
• Highlights
• Installation
• Quick Start
• CLI
• What It Detects
• Model Analysis
• Architecture
• Development

Skill Doctor is for the moment when your local agent setup stops being obvious.

• "Why did Codex or OpenClaw trigger this skill instead of the other one?"
• "Which project skill overrides the global one I thought was active?"
• "Which skills contain shell, secret, subprocess, network, or destructive patterns?"
• "What changed between yesterday's scan and today's workspace state?"

It gives you a local inspector for precedence, conflicts, risky patterns, and scan history before those problems turn into invisible prompt behavior.

Run the UI for the current project:

npx --package @xiguawang/skill-doctor skill-doctor

Then click Run new scan.

Without any model configuration, you can already inspect:

• discovered skill roots
• precedence winners and competing definitions
• duplicate names and trigger overlap
• local static risk signals
• stored scan snapshots and history

If you later configure a model provider, Skill Doctor adds summarized findings and recommendations on top of the same local scan.

scan local skill roots
        ->
derive precedence, conflicts, and risk signals
        ->
build a structured model-analysis payload
        ->
store immutable snapshots globally
        ->
inspect everything in a local React UI

As local and project-level agent skills grow, it becomes difficult to answer simple operational questions:

• Which skill is actually active?
• Why did one skill override another?
• Which trigger phrase is ambiguous?
• Which skill definitions deserve closer review?

Skill Doctor treats skills as inspectable infrastructure instead of hidden behavior.

npx --package @xiguawang/skill-doctor skill-doctor

npm install -g @xiguawang/skill-doctor
skill-doctor

Or run it without a global install:

npx --package @xiguawang/skill-doctor skill-doctor

By default, skill-doctor:

• uses the current working directory as the default project context
• binds the local server to 127.0.0.1
• starts the local UI on http://localhost:4173
• attempts to open the browser
• does not run a scan until you trigger one in the UI or pass --scan

npm install
npm run build
npm run serve

skill-doctor

skill-doctor --scan

skill-doctor-scan --project /path/to/project

skill-doctor-scan --project /path/to/project --markdown ./skill-report.md

Starts the local web application.

skill-doctor [--project <path>] [--port <number>] [--app-home <path>] [--no-open] [--scan]

Common examples:

skill-doctor
skill-doctor --scan
skill-doctor --project /path/to/project
skill-doctor --no-open
skill-doctor --host 0.0.0.0

Runs a scan without starting the UI.

skill-doctor-scan [--project <path>] [--output <file>] [--markdown <file>] [--analysis-language <en|zh-CN>] [--app-home <path>]

Common examples:

skill-doctor-scan --project .
skill-doctor-scan --project . --output ./scan.json
skill-doctor-scan --project . --markdown ./report.md
skill-doctor-scan --project . --analysis-language zh-CN

• Installed skills across project, global, and system scopes
• Standard OpenClaw roots including <workspace>/skills, <workspace>/.agents/skills, ~/.agents/skills, and ~/.openclaw/skills
• OpenClaw skills.load.extraDirs imported automatically from ~/.openclaw/openclaw.json when present
• Root discovery confidence and discovery method
• Precedence chains and likely winners
• Duplicate normalized skill names
• Trigger overlaps and ambiguous activations
• Static local risk patterns in skill files
• Missing or weak metadata such as absent trigger phrases

For OpenClaw, Skill Doctor now discovers the standard roots above and also imports skills.load.extraDirs from ~/.openclaw/openclaw.json when that file is present. Manual extraRoots still work as an override for custom or non-standard layouts. Bundled OpenClaw install-time skills are not modeled yet.

The repository currently describes the key views below, but still needs committed screenshot or GIF assets. That is the next documentation upgrade for conversion.

The main dashboard is built around a single reading path: current workspace context, top-level metrics, history access, settings, and scan entry points. The hero panel keeps the product value obvious, while the right-hand summary block surfaces the current dataset and key counts without forcing the user into drawers first.

The analysis view focuses on two things side by side: model-generated findings on the left and concrete scanned roots on the right. This keeps conclusions and evidence in the same viewport, which is especially useful when reviewing multi-agent workspaces with mixed confidence levels across project and global roots.

Skill Doctor can enrich each scan with model analysis through an OpenAI-compatible chat/completions endpoint.

The flow is:

1. Skill Doctor performs a local static scan.
2. It builds a structured compact payload from the scan.
3. If model configuration is present, it sends that payload to the configured model endpoint.
4. It stores the model summary, findings, recommendations, and spotlights in the snapshot.

Important details:

• Configure apiKey, baseUrl, and model in the UI when you want model-assisted review
• The UI does not read back the full stored API key; it only shows configured state and a masked hint
• The local scanner ranks skills before sending them to the model
• UI-triggered scans request model output in the current UI language
• CLI scans default to English and support --analysis-language zh-CN
• If model config is missing or the provider fails, the local scan still completes and records the analysis state

Skill Doctor keeps its state outside the inspected project by default:

~/.skill-doctor/

This includes:

• config.json
• scan snapshots
• local history used by the UI

Skill Doctor is a local-first application with four runtime layers:

Current project
    |
    v
Root discovery + local static scanner
    |
    +--> precedence / conflicts / risk signals / local priority
    |
    v
Structured analysis payload
    |
    +--> OpenAI-compatible model analysis
    |
    v
Global storage (~/.skill-doctor/)
    |
    +--> config.json
    +--> scan snapshots
    +--> history metadata
    |
    v
Local Node API
    |
    v
React UI

• src-core/scanner/: discovers roots, parses skills, computes precedence, conflicts, issues, and local risk signals
• src-core/analysis/: builds the structured compact payload, calls the configured model endpoint, and normalizes analysis output
• src-core/storage/: manages global config and immutable scan snapshots under ~/.skill-doctor/
• scripts/dev-server.ts: serves the built frontend and exposes local APIs for config, scans, history, and directory browsing
• src/: renders the React UI for history, settings, scan creation, analysis, and skill inspection

1. The user opens the local UI with the current directory as the default project context.
2. A scan request triggers root discovery and local static analysis.
3. The scanner builds a typed snapshot and a structured payload for the model.
4. Model analysis returns summary, findings, recommendations, and skill spotlights.
5. The final snapshot is stored in ~/.skill-doctor/ and immediately becomes available in the history-backed UI.

• English and Simplified Chinese interface
• Top-bar language switcher
• History drawer with filtering, deletion, and broken-record handling
• Settings drawer for global model config and extra scan roots
• Project path input and home-directory-based folder picker
• Recent project paths from local history
• Skill detail view with local priority breakdown

Built-in discovery currently covers common project and global roots for:

• OpenClaw
• Codex
• Claude
• Cursor
• Copilot
• GitHub

You can also define extra absolute scan roots in settings when your environment uses custom paths.

Skill Doctor supports lightweight OpenClaw integration out of the box.

Covered OpenClaw roots:

• <workspace>/skills
• <workspace>/.agents/skills
• ~/.agents/skills
• ~/.openclaw/skills
• skills.load.extraDirs imported automatically from ~/.openclaw/openclaw.json

Current OpenClaw coverage:

• scans OpenClaw workspace, project-agent, personal-agent, managed, and config-driven extra skill roots
• models the common precedence chain across those roots
• shows conflicts, override chains, risks, and skill details in the same UI as other agent ecosystems
• does not yet model bundled OpenClaw install-time skills

Fastest way to use it from an OpenClaw workspace:

npx skill-doctor --scan

Or scan only and keep the output local:

npx skill-doctor-scan --project . --output ./skill-doctor-openclaw-scan.json

Copy this prompt into OpenClaw when you want a lightweight Skill Doctor integration in the current workspace:

Integrate Skill Doctor into the current OpenClaw workspace with the lightest possible setup.

Requirements:
1. Treat the current directory as the target workspace.
2. Do not modify existing OpenClaw skills unless absolutely necessary.
3. Use Skill Doctor as an external inspector, not as a replacement for the current skill layout.
4. Prefer one-command usage first: `npx skill-doctor --scan`.
5. If a scan-only artifact is more appropriate, run `npx skill-doctor-scan --project . --output ./skill-doctor-openclaw-scan.json`.
6. Preserve any existing OpenClaw `skills.load.extraDirs` behavior.
7. After setup, summarize:
   - which OpenClaw roots were detected
   - which skill copy wins in each precedence chain
   - any high-risk skills or trigger conflicts
   - the exact command to rerun the inspection later

Constraints:
- Keep the integration local-first.
- Do not add unnecessary dependencies.
- Do not rewrite the repository structure.
- If configuration is missing for model analysis, still complete the local scan and report that model analysis was skipped or failed.

This repository includes a demo workspace for validation:

examples/demo-workspace/

It is useful for testing:

• override behavior
• trigger overlap detection
• high-risk and medium-risk local patterns
• missing metadata issues
• local-priority ranking before model analysis
• OpenClaw precedence across workspace, project agent, personal agent, managed local, and config-driven extra roots

Run it with:

npm run scan:demo

Run the OpenClaw-specific fixture with:

npm run scan:demo:openclaw

Install dependencies:

npm install

Type-check:

npm run typecheck

Build the frontend:

npm run build

Run the local app from the repository:

npm run serve

Build package artifacts:

npm run build:package

src/          React frontend
src-core/     scanner, analysis, storage, validation
scripts/      CLI and local server entry points
public/       demo data and static assets
docs/         plans, reports, and product notes
examples/     demo workspace for validation

• Per-agent precedence rules instead of a single generic precedence model
• Better diffing across projects or machines
• Stronger repair suggestions and fix generation
• More portable packaging and installation workflows

No license file is included in this repository snapshot yet.