opencode-skills-doctor 0.3.2 → 0.3.4

package/README.md

@@ -8,9 +8,24 @@ Local scanner, linter, fixer, updater and **OpenCode plugin** for skills — zer
 
 ## Why
 
-On every model step, OpenCode advertises every skill that has a `description` — the model sees `ID + name + description` for each of them. As skills pile up, this turns into **context bloat, colliding descriptions, shadowed IDs, edits to the wrong file, and skills that silently stop working**.
+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.
 
-`skills-doctor` surfaces all of that locally, and can also update skills from an HTTP catalog and verify the result.
+**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.
+
+**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
 
@@ -114,22 +129,31 @@ It registers:
 
 ### OpenCode 1.x
 
-1.x uses a different plugin API. Point the `plugin` array at the `/v1` entry:
+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
-// opencode.json (1.x)
 {
-  "plugin": ["opencode-skills-doctor/v1"]
+  "plugin": ["C:\\Users\\<you>\\.config\\opencode\\plugins\\skills-doctor.js"]
 }
 ```
 
-It registers the same `skills_doctor` tool (1.x has no `/skills-doctor` command hook). The package must be installed where OpenCode resolves plugins, e.g.:
-
-```powershell
-npm i --prefix ~/.config/opencode opencode-skills-doctor
-```
+It registers the same `skills_doctor` tool (1.x has no `/skills-doctor` command hook).
 
-> The package root entry (`import "opencode-skills-doctor"`) is the V2 plugin and requires OpenCode 2.x. The CLI works on both lines.
+> The package root entry is the V2 plugin and requires OpenCode 2.x. The CLI works on both lines.
 
 ## Rules
 
@@ -174,12 +198,28 @@ npm i --prefix ~/.config/opencode opencode-skills-doctor
 
 `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 }`).
 
-## Known limitations
+## 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 `/skills-doctor` command** — only the `skills_doctor` tool.
+
+**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**
 
-- `check` is offline; use `update --check-only` to ask a catalog for new versions.
+- 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.
-- Config precedence is assumed: global config < project config < `skills` array order. If OpenCode differs, trust the runtime.
-- No automatic file rewriting yet (v0.2 plans `--fix`: archive shadowed definitions, normalize IDs, trim descriptions).
+- `check` is offline; ask a catalog for new versions with `update --check-only`.
+- Config precedence is assumed: global config < project config < `skills` array order.
 
 ## Roadmap
 

package/README.zh-CN.md

@@ -8,9 +8,24 @@ OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **Open
 
 ## 为什么需要它
 
-opencode 每个模型步骤都会把所有「有 description 的 skill」展示给模型（`ID + name + description`）。skill 一多、一杂，就会出现**上下文膨胀、描述撞车、同 ID 互相遮蔽、改错文件、静默失效**。
+opencode 每个模型步骤都会把所有「有 description 的 skill」展示给模型（`ID + name + description`）。skill 不是免费的——它是**每一次请求都要交的上下文税**。
 
-`skills-doctor` 在本地把这些都查出来，并且能从 HTTP catalog 更新 skill、校验更新结果。
+**成本有多大**：29 个 skill、描述偏长，就是**每步 3000+ tokens**。一次 100 步的会话，光 skill 目录就烧掉约 30 万 tokens，模型还没开始读你一行代码。
+
+**会出什么问题**：skill 越攒越多，就会出现
+- 同 ID 互相遮蔽——你改的可能是一份永远不会加载的文件；
+- 描述越来越像，模型选错 skill；
+- 一堆没人注意的死重。
+
+**`skills-doctor` 做什么**：把成本量出来、把「谁真正生效」指出来，并直接修：
+
+- `check` —— 报告重复/遮蔽、超长描述、超大正文、每步 token 预算，并给修复建议；
+- `scan` —— 列出每个 skill 的来源、优先级和成本；
+- `fix` —— 归档被遮蔽的重复定义（可逆），或隐藏低频 skill（`autoinvoke: false`，仍可 `@id` 加载）；
+- `update` —— 按版本从 HTTP catalog 同步 skill，带 lockfile 和 drift 检测；
+- 插件 —— 在 OpenCode 会话里暴露 `skills_doctor` 工具 / `/skills-doctor` 命令。
+
+CLI 和插件都同时支持 **OpenCode 1.x 和 2.x**。
 
 ## 快速开始
 
@@ -114,22 +129,31 @@ skills-doctor update --into .\team-skills
 
 ### OpenCode 1.x
 
-1.x 用的是另一套插件 API，把 `plugin` 数组指向 `/v1` 入口：
+1.x 用的是另一套插件 API：npm 插件会解析 `./server` 导出，运行时需要 `@opencode-ai/plugin`。最稳的接法是加一个一行的本地插件文件。
+
+1. 先把包装到 OpenCode 解析插件的位置：
+
+```powershell
+npm i --prefix ~/.config/opencode opencode-skills-doctor
+```
+
+2. 新建 `~/.config/opencode/plugins/skills-doctor.js`：
+
+```js
+export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"
+```
+
+3. 在 `opencode.json` 里引用（1.x 用 `plugin`，不是 `plugins`）：
 
 ```jsonc
-// opencode.json（1.x）
 {
-  "plugin": ["opencode-skills-doctor/v1"]
+  "plugin": ["C:\\Users\\<you>\\.config\\opencode\\plugins\\skills-doctor.js"]
 }
 ```
 
-它会注册同样的 `skills_doctor` 工具（1.x 没有 `/skills-doctor` 命令钩子）。需要把包装在 OpenCode 能解析插件的位置，例如：
-
-```powershell
-npm i --prefix ~/.config/opencode opencode-skills-doctor
-```
+它会注册同样的 `skills_doctor` 工具（1.x 没有 `/skills-doctor` 命令钩子）。
 
-> 包根入口（`import "opencode-skills-doctor"`）是 V2 插件，需要 OpenCode 2.x；CLI 两条线都能用。
+> 包根入口是 V2 插件，需要 OpenCode 2.x；CLI 两条线都能用。
 
 ## 检测规则
 
@@ -174,12 +198,28 @@ npm i --prefix ~/.config/opencode opencode-skills-doctor
 
 `check --json` / `scan --json` / `update --json` 都会输出结构化 JSON，方便接 CI 或做网页报告。字段包括 `summary`、`findings[]`、`skills[]`（含 `managed: { version, url, root }`）。
 
-## 已知限制
+## 注意事项与已知限制
+
+**安装 / 插件**
+
+- OpenCode **2.x**：在 `opencode.jsonc` 加 `"plugins": ["opencode-skills-doctor"]` 即可。
+- OpenCode **1.x**：需要 `npm i --prefix ~/.config/opencode opencode-skills-doctor`，再加一个一行本地插件文件（`export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"`）——因为 1.x 解析插件的机制不同，且 `@opencode-ai/plugin` 是可选 peer 依赖。
+- 1.x **没有 `/skills-doctor` 命令**，只有 `skills_doctor` 工具。
+
+**安全性 / 行为**
+
+- `fix` 默认**只处理项目内**；要动全局来源加 `--all`。归档文件进入 `.skills-doctor-archive/<时间戳>/`（可逆，是移动不是删除）。
+- `fix` 只处理**被遮蔽**的定义，永远不改生效版本，也不会重写描述或正文。
+- `fix --hide` 只加 `metadata.opencode/autoinvoke: false`，skill 仍可用 `@id` 加载。
+- 遮蔽判定遵循 OpenCode 优先级：注册越后越优先；同序时 `SKILL.md` 目录形式优先。如与实际运行不一致，以实际运行为准。
+- 它**不是安全沙箱**：只审计配置和文件，不限制 agent 能做什么。
+
+**度量**
 
-- 不联网时 `check` 只做本地检查；catalog 是否有新版本要用 `update --check-only`。
-- token 估算是启发式（CJK 约 1.7 字/token，其余约 4 字符/token），用于横向比较，不是精确计费。
-- 配置优先级假设：全局配置 < 项目配置 < `skills` 数组顺序；如与 opencode 实现有出入，以实际加载结果为准。
-- 还不会自动改文件（v0.2 计划加 `--fix`：归档被遮蔽的定义、规范化 ID、裁剪描述）。
+- 默认 `budget`（1200 tokens）是建议值，不是硬限制；用 `.skills-doctor.json` 或 `--budget` 调整。
+- token 是启发式估算（CJK 约 1.7 字/token，其余约 4 字符/token），用于横向比较，不是精确计费。
+- `check` 不联网；要看 catalog 新版本用 `update --check-only`。
+- 配置优先级假设：全局配置 < 项目配置 < `skills` 数组顺序。
 
 ## Roadmap
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.3.2",
-  "description": "Local scanner, linter, fixer and updater for OpenCode skills, with OpenCode 2.x and 1.x plugin entries",
+  "version": "0.3.4",
+  "description": "Audit, fix and update OpenCode skills: measure per-step context cost, catch shadowed duplicates, archive safely and sync from catalogs. Works on OpenCode 1.x and 2.x.",
   "type": "module",
   "exports": {
     ".": "./src/plugin.mjs",
     "./plugin": "./src/plugin.mjs",
+    "./server": "./src/plugin-v1.mjs",
     "./v1": "./src/plugin-v1.mjs",
     "./audit": "./src/audit.mjs"
   },