npm - opencode-skills-doctor - Versions diffs - 0.6.1 → 0.6.2 - Mend

opencode-skills-doctor 0.6.1 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md +86 -495
package/docs/README.zh-CN.md +11 -0
package/docs/REFERENCE.md +541 -0
package/docs/assets/banner.svg +49 -0
package/docs/assets/report.png +0 -0
package/docs/assets/social-preview.png +0 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,547 +1,138 @@
-# skills-doctor
+<p align="center">
+  <img src="https://raw.githubusercontent.com/wangyuchen5110/opencodeplugginprogram/main/docs/assets/banner.svg" alt="skills-doctor — audit the hidden token cost of agent skills" width="100%">
+</p>
-[![npm](https://img.shields.io/npm/v/opencode-skills-doctor)](https://www.npmjs.com/package/opencode-skills-doctor)
-[![downloads](https://img.shields.io/npm/dw/opencode-skills-doctor)](https://www.npmjs.com/package/opencode-skills-doctor)
-[![node](https://img.shields.io/node/v/opencode-skills-doctor)](https://www.npmjs.com/package/opencode-skills-doctor)
-[![license](https://img.shields.io/npm/l/opencode-skills-doctor)](LICENSE)
-[![test](https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml/badge.svg)](https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml)
+<p align="center">
+  <a href="https://www.npmjs.com/package/opencode-skills-doctor"><img src="https://img.shields.io/npm/v/opencode-skills-doctor?style=flat-square&color=3fb950" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/opencode-skills-doctor"><img src="https://img.shields.io/npm/dw/opencode-skills-doctor?style=flat-square" alt="npm downloads"></a>
+  <a href="https://github.com/wangyuchen5110/opencodeplugginprogram/stargazers"><img src="https://img.shields.io/github/stars/wangyuchen5110/opencodeplugginprogram?style=flat-square&color=58a6ff" alt="GitHub stars"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-3fb950?style=flat-square" alt="Node ≥ 20">
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/opencode-skills-doctor?style=flat-square" alt="MIT license"></a>
+  <a href="https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml"><img src="https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml/badge.svg?style=flat-square" alt="tests"></a>
+</p>
-Local scanner, linter, fixer, updater and **OpenCode plugin** for agent skills — zero dependencies, Node ≥ 20.
+<p align="center">
+  <b>Audit, fix and update the skills your coding agent loads.</b><br>
+  Measure the per-step token tax, find shadowed duplicates and broken references — then fix them safely.
+</p>
-**English** | [简体中文](docs/README.zh-CN.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md)
+<p align="center">
+  English · <a href="docs/README.zh-CN.md">简体中文</a> · <a href="CHANGELOG.md">Changelog</a> · <a href="SECURITY.md">Security</a> · <a href="docs/REFERENCE.md">Full reference</a>
+</p>
-## At a glance
+---
-| | |
-|---|---|
-| **What it is** | Audit, fix and update the skills your coding agent loads |
-| **Interfaces** | CLI · OpenCode plugin (1.x / 2.x) · MCP server (Claude Code, Codex, DSH, …) · Grok CLI compatible |
-| **Skill sources** | `.opencode/skills`, `.claude/skills`, `.agents/skills`, `.grok/skills`, `.cursor/skills`, `opencode.json(c)` entries, HTTP catalogs |
-| **What it finds** | shadowed IDs, duplicates, long descriptions, oversized bodies, per-step token budget, broken file references, invalid frontmatter, empty bodies, stale skills |
-| **What it fixes** | archives shadowed definitions (reversible), hides low-frequency skills, syncs catalogs with drift detection |
-| **Reports** | terminal, JSON, or a self-contained HTML report (`--html [file] --open`) |
-| **Plan** | exact token savings: trim descriptions and/or hide skills, projected over N steps |
-| **Cost** | CLI: 0 tokens. Plugin: ~191 tokens/step for the tool definition, plus a one-time warning per session |
-| **Requirements** | Node ≥ 20, zero runtime dependencies |
-| **Quality** | 58 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
-## Why
+## The 30-second version
-On every model step, OpenCode advertises every skill that has a `description` — the model sees `ID + name + description` for each of them. Skills are not free: they are a permanent context tax on every request.
+Every agent skill with a `description` is advertised to the model on **every single step**. On a machine with 29 skills that is **~3,074 tokens per step** — before the model reads a line of your code. Duplicates silently shadow each other, descriptions drift, and references to files that no longer exist go unnoticed.
-**What this costs.** 29 skills with long descriptions ≈ **3,000+ tokens every step**. Over a 100-step session that is ~300k tokens of pure overhead — spent before the model reads a single line of your code. And that is only 29 skills: many users have far more they downloaded without noticing, some already out of date. This tool helps you understand your skill repository much better.
+`skills-doctor` measures that cost, shows which definition actually wins, and fixes it:
-**What can go wrong.** As skills pile up:
-- duplicate IDs silently shadow each other — you may be editing a file that never loads;
-- descriptions drift until the model picks the wrong skill;
-- half the catalog is dead weight nobody noticed.
+| | |
+|---|---|
+| **Find** | token budget, shadowed duplicates, flat/dir collisions, long descriptions, oversized bodies, broken references, invalid frontmatter, stale skills |
+| **Fix** | archive shadowed definitions (reversible), hide low-frequency skills, trim descriptions with a measured plan |
+| **Update** | sync skills from HTTP catalogs with a lockfile, drift detection and `--prune` |
+| **Report** | terminal, JSON, or a self-contained HTML report |
+| **Run it** | CLI · OpenCode plugin (1.x/2.x/Desktop) · MCP server · DeepSeek Harness skill |
-**What `skills-doctor` does.** It measures the cost, shows which definition actually wins, and fixes it:
+## See it
-- `check` — report duplicates/shadowing, long descriptions, oversized bodies and the per-step token budget, with fix hints;
-- `scan` — list every skill with its source, precedence and cost;
-- `fix` — archive shadowed duplicates (reversible) or hide low-frequency skills (`autoinvoke: false`, still loadable with `@id`);
-- `update` — sync skills from HTTP catalogs by version, with a lockfile and drift detection;
-- plugin — expose the audit as a `skills_doctor` tool / `/skills-doctor` command inside OpenCode.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/wangyuchen5110/opencodeplugginprogram/main/docs/assets/report.png" alt="skills-doctor HTML report" width="82%">
+</p>
-Works as a CLI and a plugin on **OpenCode 1.x and 2.x**.
+A real `check --html` run: summary cards, the context-budget bar, filterable findings, and the exact potential savings.
 ## Quick start
 ```powershell
-# Run straight from the repo (no install)
-node bin/skills-doctor.mjs check
-# Or install it locally
-npm link
-skills-doctor check
-```
-What a run looks like:
-```text
-skills-doctor 0.4.1
-  sources: 5 (2 exist)  definitions: 29  unique IDs: 29  advertised: 29  description budget: ~3074 tokens
-[E] token-budget   Advertised skill descriptions cost about 3074 tokens per model step, over 2x the 1200 budget
-[W] long-description  "deep-research" description is 917 chars; it is paid on every model step
-[W] large-body     "academic-paper" body is about 9980 tokens; invoking it pastes the whole body into context
-...
-1 error, 18 warn, 0 info
-Hints:
-  - Trim descriptions, or hide low-frequency skills with metadata.opencode/autoinvoke: false.
-  - Move details into references/ and keep SKILL.md to the workflow.
-```
-## Commands
-All commands accept `--lang en|zh` (default: auto from the system locale) and `--json`.
-### `check` (default)
-Scans every skill source, reports problems, the context budget and fix hints.
-```powershell
-skills-doctor check
-skills-doctor check --json
-skills-doctor check --budget 800 --strict    # for CI
-skills-doctor check --root .\some-project --no-global
-skills-doctor check --html report.html       # self-contained HTML report
-skills-doctor check --html report.html --open
-```
-### HTML report
-`--html [file]` writes a single self-contained HTML file (no external assets):
-- summary cards and a context-budget bar;
-- findings filterable by severity and text;
-- a skill table with scope, token cost, description preview and file path;
-- default path `./skills-report.html` when `--html` is given without a value; `--open` launches the browser.
-The plugin and MCP tool accept the same thing as an `html` argument, so the agent can ask you where to save it — for example: *"save the report to D:\reports\skills.html"*.
-### `plan` (how many tokens can I actually save?)
-```powershell
-skills-doctor plan
-skills-doctor plan --budget 800 --desc-target 160 --steps 200
-skills-doctor plan --json
-```
-It answers "how much can I cut, exactly?":
-- only **advertised** definitions cost tokens — archiving shadowed duplicates saves 0, and the plan says so instead of pretending;
-- **Option A** trims every description longer than `--desc-target` (default 160 chars, cut at sentence boundaries) and computes the exact saving;
-- **Option B** hides the fewest skills needed to reach the budget (still loadable with `@id`; picking the largest savings first is optimal for "minimal hides");
-- **Recommended** trims first, then hides, with no double counting, and projects the saving over `--steps` model steps (default 100).
-`check` prints a one-line pointer when you are over budget, and the HTML report shows the same potential-savings card.
-### `scan`
-Lists every skill with its source, precedence, whether the model can see it, and token cost.
-```powershell
-skills-doctor scan
-```
-`*` marks the definition that actually wins (later registration = higher precedence).
-### `fix`
-Archives definitions that are shadowed — files that never load because another source defines the same ID. The move is reversible: files go into `.skills-doctor-archive/<timestamp>/` inside the same source, which OpenCode ignores (dot-directory).
-```powershell
-skills-doctor fix --dry-run   # preview what would be archived
-skills-doctor fix
-skills-doctor fix --hide academic-paper,deep-research --dry-run   # hide low-frequency skills
-```
-- Only shadowed duplicates are touched; the effective definition is never moved;
-- Files installed by `update` are skipped — use `update` to bring them back;
-- Default scope is project-only; pass `--all` to also archive global sources;
-- After fixing, `check` should report no `shadowed` findings.
-### `update` (updater)
-Reads HTTP catalogs from the `skills` array in `opencode.json(c)`, compares `version`, and downloads whatever changed.
-```powershell
-skills-doctor update                 # installs into .opencode/skills by default (where opencode reads)
-skills-doctor update --check-only    # only report available updates
-skills-doctor update --into .\team-skills
-```
-- The output directory is a real OpenCode skill directory, so **`check` picks the update up immediately**;
-- Overwrites files in place and **deletes files that the new version no longer lists** (no stale leftovers from the old version);
-- Writes `.skills-doctor.lock.json` (schema v2: a sha1 for every file);
-- `check` reads that lock: shows managed versions, detects hand edits (`managed-drift`) and missing files (`managed-missing`);
-- Running `update` again re-downloads drifted files (self-healing);
-- Use `--prune` to delete skills that disappeared from the catalog (by default they are reported but kept).
-## Does the plugin cost tokens?
-Local execution is free, but any tool registered with the model is visible on every request. Measured on this repo:
-| Component | Tokens | When |
-|---|---|---|
-| Scan / lint / fix / update (local work) | **0** | always |
-| `skills_doctor` tool definition | **~191** | every request |
-| Budget warning injected into the system prompt | **~60–80** | once per session, only when over budget |
-| Audit report returned by the tool | **~940** | only when the tool is actually called |
-So the plugin trades a small fixed overhead for the agent being able to audit by itself. In the example above the skill descriptions cost 3,074 tokens per step; dropping that to the 1,200 budget saves more than 10× the plugin overhead. If you want **zero** context cost, don't install the plugin — run `npx opencode-skills-doctor check` from the terminal or CI instead.
-## Self-update
-`skills-doctor` checks npm for a newer version of itself at most once per 24 hours (skipped in CI, non-TTY and `--json` runs):
-```powershell
-skills-doctor upgrade            # check now
-skills-doctor upgrade --open     # check and open the GitHub release page
-skills-doctor upgrade --apply    # npm install -g opencode-skills-doctor@latest
-```
-Opt out permanently in `.skills-doctor.json`:
-```json
-{ "checkUpdates": "off" }
-```
-| Value | Behavior |
-|---|---|
-| `"notify"` (default) | print a one-line notice when a newer version exists |
-| `"open"` | same, plus opens the release page in the browser |
-| `"off"` | never check |
-Per run: `--no-update-check`. Per environment: `SKILLS_DOCTOR_UPDATE_CHECK=0`. The plugin injects the same notice into the system prompt once per session when an update exists. Cached state lives in `~/.skills-doctor/self-update.json`.
-## Configuration
-Optional `.skills-doctor.json` in the working directory (or pass `--config <file>`):
-```json
-{
-  "budget": 1200,
-  "staleDays": 180,
-  "lang": "en",
-  "checkUpdates": "notify",
-  "rules": { "long-description": "off", "hidden-skill": "info" },
-  "ignore": ["legacy-skill"]
-}
-```
-`rules` accepts `off`, `info`, `warn` or `error`; `ignore` drops findings that only involve those IDs; `checkUpdates` is `notify` / `open` / `off`. CLI flags override the file.
-## OpenCode plugin
-The package also exports an OpenCode 2.x plugin:
-```jsonc
-// opencode.jsonc
-{
-  "plugins": ["opencode-skills-doctor"]
-}
-```
-It registers:
-- the `skills_doctor` tool (namespace `skills`) — the agent can audit with `{ directory?, budget?, html? }` and gets a markdown report;
-- the `/skills-doctor` command — asks the agent to run the audit and summarize fixes;
-- `/skills-report` — asks where to save an HTML report, then writes it;
-- `/skills-upgrade` — checks whether skills-doctor itself has a newer version.
-`@opencode/plugin` is an optional peer dependency; OpenCode provides it at runtime.
-### OpenCode 1.x
+# terminal report
+npx -y opencode-skills-doctor check
-1.x uses a different plugin API: it resolves the `./server` export for npm plugins and needs `@opencode-ai/plugin` at runtime. The reliable setup is a one-line local plugin file.
+# how many tokens can I actually cut?
+npx -y opencode-skills-doctor plan
-1. Install the package where OpenCode resolves plugins:
-```powershell
-npm i --prefix ~/.config/opencode opencode-skills-doctor
+# shareable HTML report
+npx -y opencode-skills-doctor check --html report.html --open
 ```
-2. Create `~/.config/opencode/plugins/skills-doctor.js`:
-```js
-export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"
-```
+Example `plan` output on a real setup:
-3. Reference it from `opencode.json` (1.x uses `plugin`, not `plugins`):
+```text
+current: ~3,124 tokens/step (30 advertised)   budget: 1,200
-```jsonc
-{
-  "plugin": ["C:\\Users\\<you>\\.config\\opencode\\plugins\\skills-doctor.js"]
-}
+Option A — trim descriptions   26 skills → 1,606  (−1,518)
+Option B — hide skills         11 skills → 1,200  (−1,924)
+Recommended                     trim 26 + hide 2 → 1,184  (−1,940)
+over 100 steps that saves ~194,000 tokens
 ```
-It registers the same `skills_doctor` tool. 1.x plugins cannot register commands, so `skills-doctor install` writes a `/skills-doctor` markdown command.
-> The package root entry is the V2 plugin and requires OpenCode 2.x. The CLI works on both lines.
-### OpenCode Desktop
-The desktop app bundles the same OpenCode core and reads the **same config directory** as the CLI (`~/.config/opencode`; its UI settings live elsewhere), so one install covers both:
+## Install
 ```powershell
-npx opencode-skills-doctor install --client desktop
-```
-- detects the app in the standard install locations and reads its bundled core version from `resources/app.asar` (e.g. 1.17.11), then uses the matching plugin API;
-- writes the same plugin entry and `/skills-doctor`, `/skills-report`, `/skills-upgrade` commands as the CLI install — restart the desktop app afterwards;
-- `--client auto` (default) prefers the CLI version when both are installed; `--client opencode` skips desktop detection;
-- `uninstall --client desktop` reverses it.
-Verified on Windows: app at `%LOCALAPPDATA%\Programs\@opencode-aidesktop\OpenCode.exe`, sharing config with the `opencode` CLI.
+# OpenCode — plugin + /skills-doctor, /skills-report, /skills-upgrade commands
+npx -y opencode-skills-doctor install              # auto-detects 1.x / 2.x / Desktop
+npx -y opencode-skills-doctor install --client desktop
-### Deep integration (one command)
-```powershell
-npx opencode-skills-doctor install
+# DeepSeek Harness — MCP tool + audit skill, one command
+npx -y opencode-skills-doctor install --client dsh
 ```
-The installer detects your OpenCode version and wires everything up:
-- **2.x** — adds `"plugins": ["opencode-skills-doctor"]` to `opencode.json(c)`;
-- **1.x** — installs the package into `~/.config/opencode`, writes the local plugin entry, generates `/skills-doctor`, `/skills-report` and `/skills-upgrade` markdown commands, sets `"type": "module"`;
-- backs up the config file as `<config>.bak-<timestamp>` before editing.
-Use `--dry-run` to preview, `--config-dir <dir>` for a custom config location, and `--no-npm` to skip the package install.
-Once installed you get:
-- the `skills_doctor` tool (with an optional `html` argument to write a report to a path you choose);
-- the `/skills-doctor` command (1.x: generated markdown command; 2.x: plugin command);
-- the `/skills-report` command (2.x) that asks where to save the HTML report;
-- the `/skills-upgrade` command (2.x) that checks for a newer skills-doctor;
-- a one-time system-prompt warning when the skill description budget is exceeded.
-### Uninstall
+**Claude Code, Codex, Grok or any MCP client** — register the server once:
 ```powershell
-npx opencode-skills-doctor uninstall
+npx -y opencode-skills-doctor mcp
 ```
-- **2.x** — removes `opencode-skills-doctor` from `plugins`;
-- **1.x** — removes the config entry, deletes the generated plugin entry and `/skills-doctor` command, and uninstalls the package (`--no-npm` skips that);
-- only files generated by the installer are deleted — anything you edited is kept and reported;
-- config files are backed up before editing; `--dry-run` previews, `--config-dir` targets a custom location.
-Your data is never touched: `.skills-doctor.json`, `.skills-doctor.lock.json` and `.skills-doctor-archive/` stay until you delete them. MCP entries in other clients (Claude Code, Codex, DSH) are per-client configs and must be removed there.
-## MCP server (Claude Code, Codex, Kimi Code, any MCP client)
-`skills-doctor mcp` speaks the Model Context Protocol over stdio and exposes one tool: `skills_doctor` with arguments `directory?`, `budget?`, `lang?` and `global?`. It does not need OpenCode installed.
-Claude Code (`.mcp.json` in the project, or your MCP config):
 ```json
-{
-  "mcpServers": {
-    "skills-doctor": { "command": "npx", "args": ["-y", "opencode-skills-doctor", "mcp"] }
-  }
-}
-```
-Codex (`~/.codex/config.toml`):
-```toml
-[mcp_servers.skills-doctor]
-command = "npx"
-args = ["-y", "opencode-skills-doctor", "mcp"]
-```
-Any other MCP client: run `npx -y opencode-skills-doctor mcp` and allow the `skills_doctor` tool.
-It scans `.opencode/skills`, `.claude/skills` and `.agents/skills` (project and global), so it can audit skills used by other agents too.
-### DeepSeek Harness (DSH)
-One command installs both the MCP tool and a skill that tells the model when to audit:
-```powershell
-npx -y opencode-skills-doctor install --client dsh
-```
-It locates `~/.dsh/profiles/<profile>/cordis.patch.yml` (default `desktop`; otherwise `--profile <name>`), inserts the `mcp-skills-doctor` row under an `- insert:` block idempotently, and copies the `skills-doctor-audit` skill into `~/.dsh/skills/`. Restart DSH (or let HMR reload the patch) to load the MCP tool; the skill is watched and appears without a restart.
-- tool name `mcp__skills_doctor__skills_doctor`, arguments `directory`, `budget`, `lang`, `global`, `html`;
-- `uninstall --client dsh` removes both the patch entry and the skill;
-- `--dsh-home <dir>` for a non-standard DSH home.
-Manual fallback — DSH patches add new entries under `insert`, so append this block:
-```yaml
-- insert:
-    - id: mcp-skills-doctor
-      name: "@deepseek-ai/dsh-mcp-client"
-      config:
-        serverName: skills_doctor
-        transport: stdio
-        command: npx
-        args: ["-y", "opencode-skills-doctor", "mcp"]
+{ "mcpServers": { "skills-doctor": { "command": "npx", "args": ["-y", "opencode-skills-doctor", "mcp"] } } }
 ```
-On Windows, if the stdio spawn cannot resolve `npx`, use `command: cmd` and `args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`.
-## How it works
+Nothing to configure for **skills discovery**: it reads `.opencode/skills`, `.claude/skills`, `.agents/skills`, `.grok/skills`, `.cursor/skills` and their user-level equivalents. See the [full reference](docs/REFERENCE.md) for OpenCode 1.x, DSH YAML, Codex TOML and Claude Code details.
-**Audit pipeline**
-1. Discover every skill source (see the precedence list below).
-2. Parse each `SKILL.md` / flat `.md` frontmatter and estimate its description/body cost.
-3. Resolve which definition wins for each ID (later registration wins; `SKILL.md` directory form wins ties).
-4. Run the rules, compute the per-step token budget, and emit findings with fix hints.
-**Fix pipeline**
-`fix` only touches definitions that are shadowed (never loaded): it moves them into `.skills-doctor-archive/<timestamp>/` inside the same source. The effective definition is never moved, and files managed by `update` are skipped. Scope defaults to the project; `--all` extends it to global sources.
-**Update pipeline**
-1. Fetch `<catalog>/index.json` (3 attempts with backoff on 5xx/network errors).
-2. Compare each skill's `version` with the lockfile.
-3. Download changed files (same-origin only, path traversal blocked) and write them atomically.
-4. Delete files the new version no longer lists, and clean empty directories.
-5. Verify hashes, write the lockfile, and — with `--prune` — delete skills removed from the catalog.
-`check` reads the lockfile and reports drift (`managed-drift`), missing files (`managed-missing`) and unknown lock versions (`lock-version-unsupported`). Re-running `update` re-downloads drifted files.
-### Grok CLI
-Grok discovers skills from `.grok/skills` (project, repo and `~/.grok/skills`), plus `.claude/skills`, `.cursor/skills` and `.agents/skills`. `skills-doctor` scans exactly the same locations, so:
-```powershell
-skills-doctor check --root .        # covers your Grok project skills
-skills-doctor check --root $HOME    # covers ~/.grok/skills and other user-level skills
-```
-No install step is needed — Grok loads `SKILL.md` packages natively. If your Grok build has MCP enabled, you can additionally register the MCP server above to let the model call `skills_doctor` itself.
-## Rules
-| Rule | Level | Meaning |
-|---|---|---|
-| `shadowed` | warn | Same ID defined in multiple sources; only one wins, the rest is dead weight and easy to edit by mistake |
-| `flat-dir-collision` | warn | Both `<id>.md` and `<id>/SKILL.md` exist in the same source |
-| `duplicate-content` | warn | Two skills share identical body text |
-| `near-duplicate-description` | warn | Descriptions are ≥ 75% similar; the model may pick the wrong one |
-| `missing-description` | info | No description, so the model never discovers it |
-| `long-description` | warn | Description > 240 chars (paid on every model step) |
-| `large-body` | warn | Body > 4000 tokens (pasted into context when invoked) |
-| `token-budget` | warn/error | Total advertised description tokens exceed the budget (default 1200) |
-| `too-many-skills` | warn/error | More than 60 / 100 skills are advertised |
-| `invalid-id` | info | ID is not kebab-case |
-| `hidden-skill` | info | Hidden via `opencode/autoinvoke: false` or `disable-model-invocation: true` |
-| `stale-skill` | info | Not updated within `--stale-days` |
-| `broken-reference` | warn | `references/`, `scripts/`, `assets/`, `templates/` or `examples/` path does not exist |
-| `reference-outside-skill` | info | A referenced file lives outside the skill directory (hurts portability) |
-| `invalid-frontmatter` | warn | Unclosed `---` fence, or non-string name/description / non-object metadata |
-| `empty-body` | info | Body is nearly empty, so the skill carries no instructions |
-| `managed-drift` | warn | A file installed by `update` was modified afterwards |
-| `managed-missing` | warn | Recorded in the lock, but the local file is gone |
-| `managed-unsafe` | warn | Path traversal or another unsafe path in the lock |
-| `lock-version-unsupported` | info | Lock is newer than this tool; parsed in compatibility mode |
-## Forward compatibility
-- **Lock**: supports v1 (string versions, no hashes) and v2 (per-file sha1). A newer lock version is parsed in compatibility mode, unknown fields are ignored, and a single `lock-version-unsupported` notice is emitted.
-- **Catalog `index.json`**: only `skills[].name/version/files` is read; any future fields are ignored.
-- **Skill frontmatter**: only `name`, `description`, `metadata.opencode/autoinvoke` and `disable-model-invocation` are read; everything else is ignored.
-- **Paths**: both OpenCode 2.0 locations (`.opencode/skills`, `~/.config/opencode/skills`) and compatibility locations (`.claude/skills`, `.agents/skills`, searched upward level by level).
-- The updater always writes the highest lock version this tool supports, so older readers never break on new fields.
-## Discovery sources (low → high precedence)
-1. `~/.claude/skills`
-2. project `.claude/skills` (from the project root up to the current directory)
-3. `~/.agents/skills`
-4. project `.agents/skills`
-5. `~/.cursor/skills`
-6. project `.cursor/skills`
-7. `~/.grok/skills`
-8. project `.grok/skills`
-9. `~/.config/opencode/skills`
-10. project `.opencode/skills`
-11. the `skills` array in `opencode.json(c)` (2.x) or `skills.paths` (1.x); relative paths resolve from the working directory; supports `~/`, absolute paths and HTTP catalogs
-## JSON output
-`check --json`, `scan --json` and `update --json` all print structured JSON, ready for CI or a web report. Fields include `summary`, `findings[]` and `skills[]` (with `managed: { version, url, root }`).
-## Security
-This tool reads and writes skill files. Before using it against a real setup:
-- `update` downloads catalog content **without signature verification** — treat catalogs as code;
-- `fix` / `--prune` move or delete files — preview with `--dry-run` first;
-- it is **not a sandbox** and does not constrain what an agent can do.
-See [SECURITY.md](SECURITY.md) for the full threat model, hardening checklist and private vulnerability reporting.
-## Caveats and known limitations
-**Install / plugin**
-- OpenCode **2.x**: add `"plugins": ["opencode-skills-doctor"]` to `opencode.jsonc` — done.
-- OpenCode **1.x**: needs `npm i --prefix ~/.config/opencode opencode-skills-doctor` plus a one-line local plugin file (`export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"`), because 1.x resolves plugins differently and `@opencode-ai/plugin` is an optional peer.
-- 1.x has no plugin-registered `/skills-doctor` command; `skills-doctor install` writes a markdown command file instead.
-**Safety / behavior**
-- `fix` defaults to **project-only**; pass `--all` to touch global sources. Archived files go to `.skills-doctor-archive/<timestamp>/` (reversible; originals are moved, not deleted).
-- `fix` only touches **shadowed** definitions. It never edits the effective skill and never rewrites descriptions or bodies.
-- `fix --hide` only adds `metadata.opencode/autoinvoke: false`; the skill stays loadable with `@id`.
-- Shadowing follows OpenCode's precedence: later registration wins; on a tie, the `SKILL.md` directory form wins. If the runtime disagrees, trust the runtime.
-- This is **not** a security sandbox: it audits configuration and files, it does not constrain what the agent can do.
-**Measurement**
-- The default `budget` (1200 tokens) is a recommendation, not a hard limit. Tune it with `.skills-doctor.json` or `--budget`.
-- Token counts are heuristic (CJK ≈ 1.7 chars/token, the rest ≈ 4 chars/token) — good for comparisons, not for billing.
-- `check` is offline; ask a catalog for new versions with `update --check-only`.
-- Config precedence is assumed: global config < project config < `skills` array order.
-## FAQ and troubleshooting
-**A skill I created does not appear.**
-Check: does the file have a `description`? Is it hidden via `opencode/autoinvoke: false` or `disable-model-invocation`? Is the ID derived from the path (directory name for `SKILL.md`, filename for flat `.md`)? Is an earlier/later source shadowing it? `skills-doctor scan` shows the winning definition for each ID.
-**`fix` did nothing.**
-`fix` only archives **shadowed** duplicates and defaults to project-only. Run `skills-doctor fix --dry-run` to see what it would do, and `--all` to include global sources. Content issues (long descriptions, large bodies) are reported, not rewritten.
-**`check` says the budget is exceeded but the agent feels fine.**
-The token numbers are heuristics, and the 1,200-token budget is a recommendation. Tune it with `--budget` or `.skills-doctor.json`; treat the report as a relative comparison, not billing.
+## Commands
-**Where did `fix` move my files?**
-Into `.skills-doctor-archive/<timestamp>/` inside the same skill source. Move them back to restore.
+| Command | What it does |
+|---|---|
+| `check` | audit sources, conflicts, budget and broken references (default) |
+| `plan` | exact token savings: what to trim, what to hide, projected over N steps |
+| `scan` | every skill with its source, precedence and cost |
+| `fix` | archive shadowed definitions (reversible) or hide low-frequency skills |
+| `update` | sync skills from HTTP catalogs, verify hashes, detect drift |
+| `install` / `uninstall` | wire into OpenCode (1.x/2.x/Desktop) or DeepSeek Harness |
+| `upgrade` | check for / apply a newer skills-doctor itself |
+| `mcp` | run as an MCP server |
-**Does it update skills automatically in the background?**
-No daemon. Run `skills-doctor update` when you want to sync; use `--check-only` to just list available updates.
+All commands accept `--json`, `--lang en|zh`, `--budget`, `--root` and `--no-global`. Full flags, rules and configuration live in the [reference](docs/REFERENCE.md).
-**Does it work on OpenCode 1.x?**
-Yes — the CLI works on both lines, and `skills-doctor install` wires up the 1.x plugin (local plugin entry + generated command). 1.x has no `/skills-doctor` command registration from plugins, so the installer writes a command file instead.
+## Works where you work
-**Why does the plugin cost tokens if it runs locally?**
-Executing code is free, but the tool definition is part of the model's context. That is why the CLI mode exists: zero context cost.
+| Agent | How |
+|---|---|
+| **OpenCode 2.x** | `plugins: ["opencode-skills-doctor"]` → tool + commands + budget warning |
+| **OpenCode 1.x** | `install` writes the local plugin entry and markdown commands |
+| **OpenCode Desktop** | shares the CLI config; `--client desktop` detects the app and its bundled core |
+| **DeepSeek Harness** | `install --client dsh` adds the MCP entry and the `skills-doctor-audit` skill |
+| **Claude Code / Codex** | MCP server (`npx -y opencode-skills-doctor mcp`) |
+| **Grok CLI / Cursor** | their skill roots are scanned natively |
-## Roadmap
+## Why it is safe
-- v0.6: CI governance (baseline that only reports new issues, official GitHub Action), content-aware suggestions (which skills are never used), catalog signature verification
-- Later: V1/Claude skill migration report
+- `fix` only archives **shadowed** definitions, moving them into `.skills-doctor-archive/<timestamp>/` — reversible, and the effective skill is never touched.
+- `plan` is pure math: no LLM calls, no network, no file changes.
+- `update` blocks path traversal, writes atomically, verifies sha1 and detects drift.
+- It is **not** a sandbox; read [SECURITY.md](SECURITY.md) before pointing it at a real setup.
-## Development and contributing
+## Development
 ```powershell
 npm test          # 58 tests (node test/doctor.test.mjs)
 npm run bench     # lint timing for 100/500/1000 skills
 ```
-- CI runs on ubuntu/macos/windows × Node 20/22/24; `prepublishOnly` re-runs the tests before every publish.
-- Issues and PRs are welcome: for behavior changes, open an issue first with the scenario and expected output. Link the issue in the PR.
-- Keep the CLI dependency-free and the output bilingual (`--lang en|zh`) — both are project invariants.
-- Security reports: see [SECURITY.md](SECURITY.md); do not open a public issue for vulnerabilities.
-- Release notes live in [CHANGELOG.md](CHANGELOG.md).
+CI runs ubuntu/macos/windows × Node 20/22/24; `prepublishOnly` re-runs the tests. Issues and PRs are welcome — see the [reference](docs/REFERENCE.md).
-### Project layout
-| Path | Purpose |
-|---|---|
-| `src/audit.mjs` | one-call audit used by CLI, plugin and MCP |
-| `src/discover.mjs` | source discovery, precedence, JSONC parsing |
-| `src/lint.mjs` | rules, token budget, near-duplicate detection |
-| `src/fix.mjs` | archive / hide |
-| `src/catalog.mjs` | updater, lockfile, retries, atomic writes |
-| `src/managed.mjs` | lock verification and drift detection |
-| `src/cli.mjs` | command dispatch and output |
-| `src/i18n.mjs` | English/Chinese strings |
-| `src/mcp.mjs` | MCP stdio server |
-| `src/plugin.mjs` / `src/plugin-v1.mjs` | OpenCode 2.x / 1.x entries |
-| `src/install.mjs` | one-command OpenCode integration |
+[Full reference](docs/REFERENCE.md) · [中文 README](docs/README.zh-CN.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md)
 MIT

package/docs/README.zh-CN.md CHANGED Viewed

@@ -1,5 +1,16 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/wangyuchen5110/opencodeplugginprogram/main/docs/assets/banner.svg" alt="skills-doctor" width="100%">
+</p>
+<p align="center">
+  <b>审计、修复、更新你的 coding agent 加载的 skill。</b><br>
+  量出每步 token 税，找出遮蔽重复和断链，再安全地修掉。
+</p>
 # skills-doctor
+[English](../README.md) · [完整英文参考](REFERENCE.md)
 [![npm](https://img.shields.io/npm/v/opencode-skills-doctor)](https://www.npmjs.com/package/opencode-skills-doctor)
 [![downloads](https://img.shields.io/npm/dw/opencode-skills-doctor)](https://www.npmjs.com/package/opencode-skills-doctor)
 [![node](https://img.shields.io/node/v/opencode-skills-doctor)](https://www.npmjs.com/package/opencode-skills-doctor)

package/docs/REFERENCE.md ADDED Viewed

@@ -0,0 +1,541 @@
+# skills-doctor — full reference
+Local scanner, linter, fixer, updater and **OpenCode plugin** for agent skills — zero dependencies, Node ≥ 20.
+[← Back to README](../README.md) · [简体中文](README.zh-CN.md) · [Changelog](../CHANGELOG.md) · [Security](../SECURITY.md)
+## At a glance
+| | |
+|---|---|
+| **What it is** | Audit, fix and update the skills your coding agent loads |
+| **Interfaces** | CLI · OpenCode plugin (1.x / 2.x) · MCP server (Claude Code, Codex, DSH, …) · Grok CLI compatible |
+| **Skill sources** | `.opencode/skills`, `.claude/skills`, `.agents/skills`, `.grok/skills`, `.cursor/skills`, `opencode.json(c)` entries, HTTP catalogs |
+| **What it finds** | shadowed IDs, duplicates, long descriptions, oversized bodies, per-step token budget, broken file references, invalid frontmatter, empty bodies, stale skills |
+| **What it fixes** | archives shadowed definitions (reversible), hides low-frequency skills, syncs catalogs with drift detection |
+| **Reports** | terminal, JSON, or a self-contained HTML report (`--html [file] --open`) |
+| **Plan** | exact token savings: trim descriptions and/or hide skills, projected over N steps |
+| **Cost** | CLI: 0 tokens. Plugin: ~191 tokens/step for the tool definition, plus a one-time warning per session |
+| **Requirements** | Node ≥ 20, zero runtime dependencies |
+| **Quality** | 58 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
+## Why
+On every model step, OpenCode advertises every skill that has a `description` — the model sees `ID + name + description` for each of them. Skills are not free: they are a permanent context tax on every request.
+**What this costs.** 29 skills with long descriptions ≈ **3,000+ tokens every step**. Over a 100-step session that is ~300k tokens of pure overhead — spent before the model reads a single line of your code. And that is only 29 skills: many users have far more they downloaded without noticing, some already out of date. This tool helps you understand your skill repository much better.
+**What can go wrong.** As skills pile up:
+- duplicate IDs silently shadow each other — you may be editing a file that never loads;
+- descriptions drift until the model picks the wrong skill;
+- half the catalog is dead weight nobody noticed.
+**What `skills-doctor` does.** It measures the cost, shows which definition actually wins, and fixes it:
+- `check` — report duplicates/shadowing, long descriptions, oversized bodies and the per-step token budget, with fix hints;
+- `scan` — list every skill with its source, precedence and cost;
+- `fix` — archive shadowed duplicates (reversible) or hide low-frequency skills (`autoinvoke: false`, still loadable with `@id`);
+- `update` — sync skills from HTTP catalogs by version, with a lockfile and drift detection;
+- plugin — expose the audit as a `skills_doctor` tool / `/skills-doctor` command inside OpenCode.
+Works as a CLI and a plugin on **OpenCode 1.x and 2.x**.
+## Quick start
+```powershell
+# Run straight from the repo (no install)
+node bin/skills-doctor.mjs check
+# Or install it locally
+npm link
+skills-doctor check
+```
+What a run looks like:
+```text
+skills-doctor 0.4.1
+  sources: 5 (2 exist)  definitions: 29  unique IDs: 29  advertised: 29  description budget: ~3074 tokens
+[E] token-budget   Advertised skill descriptions cost about 3074 tokens per model step, over 2x the 1200 budget
+[W] long-description  "deep-research" description is 917 chars; it is paid on every model step
+[W] large-body     "academic-paper" body is about 9980 tokens; invoking it pastes the whole body into context
+...
+1 error, 18 warn, 0 info
+Hints:
+  - Trim descriptions, or hide low-frequency skills with metadata.opencode/autoinvoke: false.
+  - Move details into references/ and keep SKILL.md to the workflow.
+```
+## Commands
+All commands accept `--lang en|zh` (default: auto from the system locale) and `--json`.
+### `check` (default)
+Scans every skill source, reports problems, the context budget and fix hints.
+```powershell
+skills-doctor check
+skills-doctor check --json
+skills-doctor check --budget 800 --strict    # for CI
+skills-doctor check --root .\some-project --no-global
+skills-doctor check --html report.html       # self-contained HTML report
+skills-doctor check --html report.html --open
+```
+### HTML report
+`--html [file]` writes a single self-contained HTML file (no external assets):
+- summary cards and a context-budget bar;
+- findings filterable by severity and text;
+- a skill table with scope, token cost, description preview and file path;
+- default path `./skills-report.html` when `--html` is given without a value; `--open` launches the browser.
+The plugin and MCP tool accept the same thing as an `html` argument, so the agent can ask you where to save it — for example: *"save the report to D:\reports\skills.html"*.
+### `plan` (how many tokens can I actually save?)
+```powershell
+skills-doctor plan
+skills-doctor plan --budget 800 --desc-target 160 --steps 200
+skills-doctor plan --json
+```
+It answers "how much can I cut, exactly?":
+- only **advertised** definitions cost tokens — archiving shadowed duplicates saves 0, and the plan says so instead of pretending;
+- **Option A** trims every description longer than `--desc-target` (default 160 chars, cut at sentence boundaries) and computes the exact saving;
+- **Option B** hides the fewest skills needed to reach the budget (still loadable with `@id`; picking the largest savings first is optimal for "minimal hides");
+- **Recommended** trims first, then hides, with no double counting, and projects the saving over `--steps` model steps (default 100).
+`check` prints a one-line pointer when you are over budget, and the HTML report shows the same potential-savings card.
+### `scan`
+Lists every skill with its source, precedence, whether the model can see it, and token cost.
+```powershell
+skills-doctor scan
+```
+`*` marks the definition that actually wins (later registration = higher precedence).
+### `fix`
+Archives definitions that are shadowed — files that never load because another source defines the same ID. The move is reversible: files go into `.skills-doctor-archive/<timestamp>/` inside the same source, which OpenCode ignores (dot-directory).
+```powershell
+skills-doctor fix --dry-run   # preview what would be archived
+skills-doctor fix
+skills-doctor fix --hide academic-paper,deep-research --dry-run   # hide low-frequency skills
+```
+- Only shadowed duplicates are touched; the effective definition is never moved;
+- Files installed by `update` are skipped — use `update` to bring them back;
+- Default scope is project-only; pass `--all` to also archive global sources;
+- After fixing, `check` should report no `shadowed` findings.
+### `update` (updater)
+Reads HTTP catalogs from the `skills` array in `opencode.json(c)`, compares `version`, and downloads whatever changed.
+```powershell
+skills-doctor update                 # installs into .opencode/skills by default (where opencode reads)
+skills-doctor update --check-only    # only report available updates
+skills-doctor update --into .\team-skills
+```
+- The output directory is a real OpenCode skill directory, so **`check` picks the update up immediately**;
+- Overwrites files in place and **deletes files that the new version no longer lists** (no stale leftovers from the old version);
+- Writes `.skills-doctor.lock.json` (schema v2: a sha1 for every file);
+- `check` reads that lock: shows managed versions, detects hand edits (`managed-drift`) and missing files (`managed-missing`);
+- Running `update` again re-downloads drifted files (self-healing);
+- Use `--prune` to delete skills that disappeared from the catalog (by default they are reported but kept).
+## Does the plugin cost tokens?
+Local execution is free, but any tool registered with the model is visible on every request. Measured on this repo:
+| Component | Tokens | When |
+|---|---|---|
+| Scan / lint / fix / update (local work) | **0** | always |
+| `skills_doctor` tool definition | **~191** | every request |
+| Budget warning injected into the system prompt | **~60–80** | once per session, only when over budget |
+| Audit report returned by the tool | **~940** | only when the tool is actually called |
+So the plugin trades a small fixed overhead for the agent being able to audit by itself. In the example above the skill descriptions cost 3,074 tokens per step; dropping that to the 1,200 budget saves more than 10× the plugin overhead. If you want **zero** context cost, don't install the plugin — run `npx opencode-skills-doctor check` from the terminal or CI instead.
+## Self-update
+`skills-doctor` checks npm for a newer version of itself at most once per 24 hours (skipped in CI, non-TTY and `--json` runs):
+```powershell
+skills-doctor upgrade            # check now
+skills-doctor upgrade --open     # check and open the GitHub release page
+skills-doctor upgrade --apply    # npm install -g opencode-skills-doctor@latest
+```
+Opt out permanently in `.skills-doctor.json`:
+```json
+{ "checkUpdates": "off" }
+```
+| Value | Behavior |
+|---|---|
+| `"notify"` (default) | print a one-line notice when a newer version exists |
+| `"open"` | same, plus opens the release page in the browser |
+| `"off"` | never check |
+Per run: `--no-update-check`. Per environment: `SKILLS_DOCTOR_UPDATE_CHECK=0`. The plugin injects the same notice into the system prompt once per session when an update exists. Cached state lives in `~/.skills-doctor/self-update.json`.
+## Configuration
+Optional `.skills-doctor.json` in the working directory (or pass `--config <file>`):
+```json
+{
+  "budget": 1200,
+  "staleDays": 180,
+  "lang": "en",
+  "checkUpdates": "notify",
+  "rules": { "long-description": "off", "hidden-skill": "info" },
+  "ignore": ["legacy-skill"]
+}
+```
+`rules` accepts `off`, `info`, `warn` or `error`; `ignore` drops findings that only involve those IDs; `checkUpdates` is `notify` / `open` / `off`. CLI flags override the file.
+## OpenCode plugin
+The package also exports an OpenCode 2.x plugin:
+```jsonc
+// opencode.jsonc
+{
+  "plugins": ["opencode-skills-doctor"]
+}
+```
+It registers:
+- the `skills_doctor` tool (namespace `skills`) — the agent can audit with `{ directory?, budget?, html? }` and gets a markdown report;
+- the `/skills-doctor` command — asks the agent to run the audit and summarize fixes;
+- `/skills-report` — asks where to save an HTML report, then writes it;
+- `/skills-upgrade` — checks whether skills-doctor itself has a newer version.
+`@opencode/plugin` is an optional peer dependency; OpenCode provides it at runtime.
+### OpenCode 1.x
+1.x uses a different plugin API: it resolves the `./server` export for npm plugins and needs `@opencode-ai/plugin` at runtime. The reliable setup is a one-line local plugin file.
+1. Install the package where OpenCode resolves plugins:
+```powershell
+npm i --prefix ~/.config/opencode opencode-skills-doctor
+```
+2. Create `~/.config/opencode/plugins/skills-doctor.js`:
+```js
+export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"
+```
+3. Reference it from `opencode.json` (1.x uses `plugin`, not `plugins`):
+```jsonc
+{
+  "plugin": ["C:\\Users\\<you>\\.config\\opencode\\plugins\\skills-doctor.js"]
+}
+```
+It registers the same `skills_doctor` tool. 1.x plugins cannot register commands, so `skills-doctor install` writes a `/skills-doctor` markdown command.
+> The package root entry is the V2 plugin and requires OpenCode 2.x. The CLI works on both lines.
+### OpenCode Desktop
+The desktop app bundles the same OpenCode core and reads the **same config directory** as the CLI (`~/.config/opencode`; its UI settings live elsewhere), so one install covers both:
+```powershell
+npx opencode-skills-doctor install --client desktop
+```
+- detects the app in the standard install locations and reads its bundled core version from `resources/app.asar` (e.g. 1.17.11), then uses the matching plugin API;
+- writes the same plugin entry and `/skills-doctor`, `/skills-report`, `/skills-upgrade` commands as the CLI install — restart the desktop app afterwards;
+- `--client auto` (default) prefers the CLI version when both are installed; `--client opencode` skips desktop detection;
+- `uninstall --client desktop` reverses it.
+Verified on Windows: app at `%LOCALAPPDATA%\Programs\@opencode-aidesktop\OpenCode.exe`, sharing config with the `opencode` CLI.
+### Deep integration (one command)
+```powershell
+npx opencode-skills-doctor install
+```
+The installer detects your OpenCode version and wires everything up:
+- **2.x** — adds `"plugins": ["opencode-skills-doctor"]` to `opencode.json(c)`;
+- **1.x** — installs the package into `~/.config/opencode`, writes the local plugin entry, generates `/skills-doctor`, `/skills-report` and `/skills-upgrade` markdown commands, sets `"type": "module"`;
+- backs up the config file as `<config>.bak-<timestamp>` before editing.
+Use `--dry-run` to preview, `--config-dir <dir>` for a custom config location, and `--no-npm` to skip the package install.
+Once installed you get:
+- the `skills_doctor` tool (with an optional `html` argument to write a report to a path you choose);
+- the `/skills-doctor` command (1.x: generated markdown command; 2.x: plugin command);
+- the `/skills-report` command (2.x) that asks where to save the HTML report;
+- the `/skills-upgrade` command (2.x) that checks for a newer skills-doctor;
+- a one-time system-prompt warning when the skill description budget is exceeded.
+### Uninstall
+```powershell
+npx opencode-skills-doctor uninstall
+```
+- **2.x** — removes `opencode-skills-doctor` from `plugins`;
+- **1.x** — removes the config entry, deletes the generated plugin entry and `/skills-doctor` command, and uninstalls the package (`--no-npm` skips that);
+- only files generated by the installer are deleted — anything you edited is kept and reported;
+- config files are backed up before editing; `--dry-run` previews, `--config-dir` targets a custom location.
+Your data is never touched: `.skills-doctor.json`, `.skills-doctor.lock.json` and `.skills-doctor-archive/` stay until you delete them. MCP entries in other clients (Claude Code, Codex, DSH) are per-client configs and must be removed there.
+## MCP server (Claude Code, Codex, Kimi Code, any MCP client)
+`skills-doctor mcp` speaks the Model Context Protocol over stdio and exposes one tool: `skills_doctor` with arguments `directory?`, `budget?`, `lang?` and `global?`. It does not need OpenCode installed.
+Claude Code (`.mcp.json` in the project, or your MCP config):
+```json
+{
+  "mcpServers": {
+    "skills-doctor": { "command": "npx", "args": ["-y", "opencode-skills-doctor", "mcp"] }
+  }
+}
+```
+Codex (`~/.codex/config.toml`):
+```toml
+[mcp_servers.skills-doctor]
+command = "npx"
+args = ["-y", "opencode-skills-doctor", "mcp"]
+```
+Any other MCP client: run `npx -y opencode-skills-doctor mcp` and allow the `skills_doctor` tool.
+It scans `.opencode/skills`, `.claude/skills` and `.agents/skills` (project and global), so it can audit skills used by other agents too.
+### DeepSeek Harness (DSH)
+One command installs both the MCP tool and a skill that tells the model when to audit:
+```powershell
+npx -y opencode-skills-doctor install --client dsh
+```
+It locates `~/.dsh/profiles/<profile>/cordis.patch.yml` (default `desktop`; otherwise `--profile <name>`), inserts the `mcp-skills-doctor` row under an `- insert:` block idempotently, and copies the `skills-doctor-audit` skill into `~/.dsh/skills/`. Restart DSH (or let HMR reload the patch) to load the MCP tool; the skill is watched and appears without a restart.
+- tool name `mcp__skills_doctor__skills_doctor`, arguments `directory`, `budget`, `lang`, `global`, `html`;
+- `uninstall --client dsh` removes both the patch entry and the skill;
+- `--dsh-home <dir>` for a non-standard DSH home.
+Manual fallback — DSH patches add new entries under `insert`, so append this block:
+```yaml
+- insert:
+    - id: mcp-skills-doctor
+      name: "@deepseek-ai/dsh-mcp-client"
+      config:
+        serverName: skills_doctor
+        transport: stdio
+        command: npx
+        args: ["-y", "opencode-skills-doctor", "mcp"]
+```
+On Windows, if the stdio spawn cannot resolve `npx`, use `command: cmd` and `args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`.
+## How it works
+**Audit pipeline**
+1. Discover every skill source (see the precedence list below).
+2. Parse each `SKILL.md` / flat `.md` frontmatter and estimate its description/body cost.
+3. Resolve which definition wins for each ID (later registration wins; `SKILL.md` directory form wins ties).
+4. Run the rules, compute the per-step token budget, and emit findings with fix hints.
+**Fix pipeline**
+`fix` only touches definitions that are shadowed (never loaded): it moves them into `.skills-doctor-archive/<timestamp>/` inside the same source. The effective definition is never moved, and files managed by `update` are skipped. Scope defaults to the project; `--all` extends it to global sources.
+**Update pipeline**
+1. Fetch `<catalog>/index.json` (3 attempts with backoff on 5xx/network errors).
+2. Compare each skill's `version` with the lockfile.
+3. Download changed files (same-origin only, path traversal blocked) and write them atomically.
+4. Delete files the new version no longer lists, and clean empty directories.
+5. Verify hashes, write the lockfile, and — with `--prune` — delete skills removed from the catalog.
+`check` reads the lockfile and reports drift (`managed-drift`), missing files (`managed-missing`) and unknown lock versions (`lock-version-unsupported`). Re-running `update` re-downloads drifted files.
+### Grok CLI
+Grok discovers skills from `.grok/skills` (project, repo and `~/.grok/skills`), plus `.claude/skills`, `.cursor/skills` and `.agents/skills`. `skills-doctor` scans exactly the same locations, so:
+```powershell
+skills-doctor check --root .        # covers your Grok project skills
+skills-doctor check --root $HOME    # covers ~/.grok/skills and other user-level skills
+```
+No install step is needed — Grok loads `SKILL.md` packages natively. If your Grok build has MCP enabled, you can additionally register the MCP server above to let the model call `skills_doctor` itself.
+## Rules
+| Rule | Level | Meaning |
+|---|---|---|
+| `shadowed` | warn | Same ID defined in multiple sources; only one wins, the rest is dead weight and easy to edit by mistake |
+| `flat-dir-collision` | warn | Both `<id>.md` and `<id>/SKILL.md` exist in the same source |
+| `duplicate-content` | warn | Two skills share identical body text |
+| `near-duplicate-description` | warn | Descriptions are ≥ 75% similar; the model may pick the wrong one |
+| `missing-description` | info | No description, so the model never discovers it |
+| `long-description` | warn | Description > 240 chars (paid on every model step) |
+| `large-body` | warn | Body > 4000 tokens (pasted into context when invoked) |
+| `token-budget` | warn/error | Total advertised description tokens exceed the budget (default 1200) |
+| `too-many-skills` | warn/error | More than 60 / 100 skills are advertised |
+| `invalid-id` | info | ID is not kebab-case |
+| `hidden-skill` | info | Hidden via `opencode/autoinvoke: false` or `disable-model-invocation: true` |
+| `stale-skill` | info | Not updated within `--stale-days` |
+| `broken-reference` | warn | `references/`, `scripts/`, `assets/`, `templates/` or `examples/` path does not exist |
+| `reference-outside-skill` | info | A referenced file lives outside the skill directory (hurts portability) |
+| `invalid-frontmatter` | warn | Unclosed `---` fence, or non-string name/description / non-object metadata |
+| `empty-body` | info | Body is nearly empty, so the skill carries no instructions |
+| `managed-drift` | warn | A file installed by `update` was modified afterwards |
+| `managed-missing` | warn | Recorded in the lock, but the local file is gone |
+| `managed-unsafe` | warn | Path traversal or another unsafe path in the lock |
+| `lock-version-unsupported` | info | Lock is newer than this tool; parsed in compatibility mode |
+## Forward compatibility
+- **Lock**: supports v1 (string versions, no hashes) and v2 (per-file sha1). A newer lock version is parsed in compatibility mode, unknown fields are ignored, and a single `lock-version-unsupported` notice is emitted.
+- **Catalog `index.json`**: only `skills[].name/version/files` is read; any future fields are ignored.
+- **Skill frontmatter**: only `name`, `description`, `metadata.opencode/autoinvoke` and `disable-model-invocation` are read; everything else is ignored.
+- **Paths**: both OpenCode 2.0 locations (`.opencode/skills`, `~/.config/opencode/skills`) and compatibility locations (`.claude/skills`, `.agents/skills`, searched upward level by level).
+- The updater always writes the highest lock version this tool supports, so older readers never break on new fields.
+## Discovery sources (low → high precedence)
+1. `~/.claude/skills`
+2. project `.claude/skills` (from the project root up to the current directory)
+3. `~/.agents/skills`
+4. project `.agents/skills`
+5. `~/.cursor/skills`
+6. project `.cursor/skills`
+7. `~/.grok/skills`
+8. project `.grok/skills`
+9. `~/.config/opencode/skills`
+10. project `.opencode/skills`
+11. the `skills` array in `opencode.json(c)` (2.x) or `skills.paths` (1.x); relative paths resolve from the working directory; supports `~/`, absolute paths and HTTP catalogs
+## JSON output
+`check --json`, `scan --json` and `update --json` all print structured JSON, ready for CI or a web report. Fields include `summary`, `findings[]` and `skills[]` (with `managed: { version, url, root }`).
+## Security
+This tool reads and writes skill files. Before using it against a real setup:
+- `update` downloads catalog content **without signature verification** — treat catalogs as code;
+- `fix` / `--prune` move or delete files — preview with `--dry-run` first;
+- it is **not a sandbox** and does not constrain what an agent can do.
+See [SECURITY.md](../SECURITY.md) for the full threat model, hardening checklist and private vulnerability reporting.
+## Caveats and known limitations
+**Install / plugin**
+- OpenCode **2.x**: add `"plugins": ["opencode-skills-doctor"]` to `opencode.jsonc` — done.
+- OpenCode **1.x**: needs `npm i --prefix ~/.config/opencode opencode-skills-doctor` plus a one-line local plugin file (`export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"`), because 1.x resolves plugins differently and `@opencode-ai/plugin` is an optional peer.
+- 1.x has no plugin-registered `/skills-doctor` command; `skills-doctor install` writes a markdown command file instead.
+**Safety / behavior**
+- `fix` defaults to **project-only**; pass `--all` to touch global sources. Archived files go to `.skills-doctor-archive/<timestamp>/` (reversible; originals are moved, not deleted).
+- `fix` only touches **shadowed** definitions. It never edits the effective skill and never rewrites descriptions or bodies.
+- `fix --hide` only adds `metadata.opencode/autoinvoke: false`; the skill stays loadable with `@id`.
+- Shadowing follows OpenCode's precedence: later registration wins; on a tie, the `SKILL.md` directory form wins. If the runtime disagrees, trust the runtime.
+- This is **not** a security sandbox: it audits configuration and files, it does not constrain what the agent can do.
+**Measurement**
+- The default `budget` (1200 tokens) is a recommendation, not a hard limit. Tune it with `.skills-doctor.json` or `--budget`.
+- Token counts are heuristic (CJK ≈ 1.7 chars/token, the rest ≈ 4 chars/token) — good for comparisons, not for billing.
+- `check` is offline; ask a catalog for new versions with `update --check-only`.
+- Config precedence is assumed: global config < project config < `skills` array order.
+## FAQ and troubleshooting
+**A skill I created does not appear.**
+Check: does the file have a `description`? Is it hidden via `opencode/autoinvoke: false` or `disable-model-invocation`? Is the ID derived from the path (directory name for `SKILL.md`, filename for flat `.md`)? Is an earlier/later source shadowing it? `skills-doctor scan` shows the winning definition for each ID.
+**`fix` did nothing.**
+`fix` only archives **shadowed** duplicates and defaults to project-only. Run `skills-doctor fix --dry-run` to see what it would do, and `--all` to include global sources. Content issues (long descriptions, large bodies) are reported, not rewritten.
+**`check` says the budget is exceeded but the agent feels fine.**
+The token numbers are heuristics, and the 1,200-token budget is a recommendation. Tune it with `--budget` or `.skills-doctor.json`; treat the report as a relative comparison, not billing.
+**Where did `fix` move my files?**
+Into `.skills-doctor-archive/<timestamp>/` inside the same skill source. Move them back to restore.
+**Does it update skills automatically in the background?**
+No daemon. Run `skills-doctor update` when you want to sync; use `--check-only` to just list available updates.
+**Does it work on OpenCode 1.x?**
+Yes — the CLI works on both lines, and `skills-doctor install` wires up the 1.x plugin (local plugin entry + generated command). 1.x has no `/skills-doctor` command registration from plugins, so the installer writes a command file instead.
+**Why does the plugin cost tokens if it runs locally?**
+Executing code is free, but the tool definition is part of the model's context. That is why the CLI mode exists: zero context cost.
+## Roadmap
+- v0.6: CI governance (baseline that only reports new issues, official GitHub Action), content-aware suggestions (which skills are never used), catalog signature verification
+- Later: V1/Claude skill migration report
+## Development and contributing
+```powershell
+npm test          # 58 tests (node test/doctor.test.mjs)
+npm run bench     # lint timing for 100/500/1000 skills
+```
+- CI runs on ubuntu/macos/windows × Node 20/22/24; `prepublishOnly` re-runs the tests before every publish.
+- Issues and PRs are welcome: for behavior changes, open an issue first with the scenario and expected output. Link the issue in the PR.
+- Keep the CLI dependency-free and the output bilingual (`--lang en|zh`) — both are project invariants.
+- Security reports: see [SECURITY.md](../SECURITY.md); do not open a public issue for vulnerabilities.
+- Release notes live in [CHANGELOG.md](../CHANGELOG.md).
+### Project layout
+| Path | Purpose |
+|---|---|
+| `src/audit.mjs` | one-call audit used by CLI, plugin and MCP |
+| `src/discover.mjs` | source discovery, precedence, JSONC parsing |
+| `src/lint.mjs` | rules, token budget, near-duplicate detection |
+| `src/fix.mjs` | archive / hide |
+| `src/catalog.mjs` | updater, lockfile, retries, atomic writes |
+| `src/managed.mjs` | lock verification and drift detection |
+| `src/cli.mjs` | command dispatch and output |
+| `src/i18n.mjs` | English/Chinese strings |
+| `src/mcp.mjs` | MCP stdio server |
+| `src/plugin.mjs` / `src/plugin-v1.mjs` | OpenCode 2.x / 1.x entries |
+| `src/install.mjs` | one-command OpenCode integration |
+MIT

package/docs/assets/banner.svg ADDED Viewed

@@ -0,0 +1,49 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="300" viewBox="0 0 1200 300" role="img" aria-label="skills-doctor — audit the hidden token cost of agent skills">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0b1220"/>
+      <stop offset="0.55" stop-color="#101a2e"/>
+      <stop offset="1" stop-color="#0d2033"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#3fb950"/>
+      <stop offset="1" stop-color="#58a6ff"/>
+    </linearGradient>
+  </defs>
+  <rect width="1200" height="300" fill="url(#bg)"/>
+  <circle cx="1070" cy="-40" r="260" fill="#1f6feb" opacity="0.10"/>
+  <circle cx="120" cy="330" r="220" fill="#3fb950" opacity="0.08"/>
+  <text x="64" y="112" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif" font-size="62" font-weight="700" fill="#f0f6fc">skills-doctor</text>
+  <text x="64" y="156" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif" font-size="23" fill="#9fb0c9">Audit the hidden token cost of your agent's skills</text>
+  <g font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif" font-size="15">
+    <rect x="64" y="196" width="112" height="34" rx="17" fill="#16233a" stroke="#2b3f5f"/>
+    <text x="120" y="218" fill="#c9d6ea" text-anchor="middle">OpenCode</text>
+    <rect x="186" y="196" width="122" height="34" rx="17" fill="#16233a" stroke="#2b3f5f"/>
+    <text x="247" y="218" fill="#c9d6ea" text-anchor="middle">Claude Code</text>
+    <rect x="318" y="196" width="86" height="34" rx="17" fill="#16233a" stroke="#2b3f5f"/>
+    <text x="361" y="218" fill="#c9d6ea" text-anchor="middle">Codex</text>
+    <rect x="414" y="196" width="78" height="34" rx="17" fill="#16233a" stroke="#2b3f5f"/>
+    <text x="453" y="218" fill="#c9d6ea" text-anchor="middle">DSH</text>
+    <rect x="502" y="196" width="86" height="34" rx="17" fill="#16233a" stroke="#2b3f5f"/>
+    <text x="545" y="218" fill="#c9d6ea" text-anchor="middle">Grok</text>
+  </g>
+  <g transform="translate(760,44)">
+    <rect width="392" height="212" rx="14" fill="#0a1120" stroke="#2b3f5f"/>
+    <circle cx="22" cy="20" r="5" fill="#ff5f56"/>
+    <circle cx="40" cy="20" r="5" fill="#ffbd2e"/>
+    <circle cx="58" cy="20" r="5" fill="#27c93f"/>
+    <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="13.5">
+      <text x="22" y="62" fill="#8b9bb4">$ npx opencode-skills-doctor check</text>
+      <text x="22" y="96" fill="#3fb950">✓ 29 skills · ~3,074 tokens/step</text>
+      <text x="22" y="128" fill="#d29922">! over budget ×2</text>
+      <text x="22" y="160" fill="#58a6ff">plan → save ~1,940 tokens/step</text>
+      <text x="22" y="192" fill="#8b9bb4">HTML report ready →</text>
+    </g>
+  </g>
+  <rect x="64" y="262" width="72" height="3" rx="1.5" fill="url(#accent)"/>
+</svg>

package/docs/assets/report.png ADDED Viewed

Binary file

package/docs/assets/social-preview.png ADDED Viewed

Binary file

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Audit, fix and update agent skills: token cost, broken references, shadowed duplicates, HTML reports, catalog sync. CLI, OpenCode plugin, MCP server; works with OpenCode, Claude Code, Codex, Grok CLI, Cursor and DeepSeek Harness.",
   "type": "module",
   "exports": {