<div align="center">

Skill Doctor

Audit coding-agent skills like infrastructure, not hidden prompt glue.

中文文档

<p> <img alt="npm" src="https://img.shields.io/badge/npm-package-161b22?style=for-the-badge&logo=npm&logoColor=white"> <img alt="react" src="https://img.shields.io/badge/react-ui-161b22?style=for-the-badge&logo=react&logoColor=61dafb"> <img alt="typescript" src="https://img.shields.io/badge/typescript-core-161b22?style=for-the-badge&logo=typescript&logoColor=3178c6"> <img alt="local first" src="https://img.shields.io/badge/local--first-workflow-161b22?style=for-the-badge"> <img alt="bilingual" src="https://img.shields.io/badge/i18n-en%20%7C%20zh--CN-161b22?style=for-the-badge"> </p> <p> Skill Doctor is a local-first inspector for coding-agent skills. It shows what is installed, which definition wins, where risk accumulates, and how a workspace behaves across project, global, and system scopes. </p> </div>

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

Navigate

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

Why People Install It

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.

Quick Proof

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.

Highlights

| Inspect | Explain | Operate | | --- | --- | --- | | Scans OpenClaw, Codex, Claude, Cursor, Copilot, GitHub, and generic skill roots | Shows precedence chains, overrides, duplicate names, and trigger overlap | Stores snapshots and config globally in ~/.skill-doctor/ | | Flags shell, network, subprocess, secret, and destructive patterns | Adds model-assisted findings on top of local static analysis | Provides a local React UI with history, filtering, deletion, and bilingual support |

At A Glance

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

Why Skill Doctor

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.

Installation

One-line app launch

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

Use as an npm package

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

Run from this repository

npm install
npm run build
npm run serve

Quick Start

Start the local UI

skill-doctor

Start the UI and run an initial scan

skill-doctor --scan

Scan a project from the CLI only

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

Generate a Markdown report

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

Product Surface

| Surface | Purpose | | --- | --- | | skill-doctor | Starts the local UI for the current project context | | skill-doctor --scan | Starts the UI and performs an initial scan | | skill-doctor-scan | Runs scans without starting the UI | | React dashboard | History, settings, roots, analysis, and skill inspection | | Global storage | Config and immutable snapshots outside the target project |

CLI

skill-doctor

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

skill-doctor-scan

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

What It Detects

• 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.

Screenshots

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

Overview

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.

Analysis And Roots

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.

Model Analysis

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

Storage

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

Architecture

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

Runtime Layers

• 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

Data Flow

1. The user opens the local UI with the current directory as the default project context.
2. A scan request triggers root discovery and