opencode-skills-doctor 0.3.10 → 0.3.12

package/README.md

@@ -1,10 +1,27 @@
 # skills-doctor
 
+[![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)
 
-Local scanner, linter, fixer, updater and **OpenCode plugin** for skills — zero dependencies, Node ≥ 20.
+Local scanner, linter, fixer, updater and **OpenCode plugin** for agent skills — zero dependencies, Node ≥ 20.
 
-**English** | [简体中文](docs/README.zh-CN.md)
+**English** | [简体中文](docs/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, …) |
+| **Skill sources** | `.opencode/skills`, `.claude/skills`, `.agents/skills`, `opencode.json(c)` entries, HTTP catalogs |
+| **What it finds** | shadowed IDs, duplicates, long descriptions, oversized bodies, per-step token budget, stale skills |
+| **What it fixes** | archives shadowed definitions (reversible), hides low-frequency skills, syncs catalogs with drift detection |
+| **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** | 41 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
 
 ## Why
 
@@ -38,6 +55,24 @@ npm link
 skills-doctor check
 ```
 
+What a run looks like:
+
+```text
+skills-doctor 0.3.11
+  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`.
@@ -95,6 +130,19 @@ skills-doctor update --into .\team-skills
 - 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.
+
 ## Configuration
 
 Optional `.skills-doctor.json` in the working directory (or pass `--config <file>`):
@@ -157,6 +205,26 @@ It registers the same `skills_doctor` tool (1.x has no `/skills-doctor` command
 
 > The package root entry is the V2 plugin and requires OpenCode 2.x. The CLI works on both lines.
 
+### 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, adds a `/skills-doctor` command, 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;
+- the `/skills-doctor` command (1.x: generated markdown command; 2.x: plugin command);
+- a one-time system-prompt warning when the skill description budget is exceeded.
+
 ## 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.
@@ -201,6 +269,29 @@ Restart DSH. The tool shows up as `mcp__skills_doctor__skills_doctor`.
 
 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.
+
 ## Rules
 
 | Rule | Level | Meaning |
@@ -277,17 +368,61 @@ See [SECURITY.md](SECURITY.md) for the full threat model, hardening checklist an
 - `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.4: content-aware suggestions (which skills are never used), catalog signature verification
 - Later: V1/Claude skill migration report
 
-## Development
+## Development and contributing
 
 ```powershell
-npm test
+npm test          # 41 tests (node test/doctor.test.mjs)
+npm run bench     # lint timing for 100/500/1000 skills
 ```
 
-Coverage: frontmatter parsing, source discovery and precedence, shadowing/duplication/budget rules, catalog download and lock, drift detection and self-healing, old/new lock compatibility, CLI JSON output and exit codes.
+- 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/README.zh-CN.md

@@ -1,10 +1,27 @@
 # skills-doctor
 
+[![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)
 
 OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **OpenCode 插件入口** —— 零依赖，Node ≥ 20。
 
-[English](../README.md) | **简体中文**
+[English](../README.md) | **简体中文** · [变更记录](../CHANGELOG.md) · [安全策略](../SECURITY.zh-CN.md)
+
+## 一张表看懂
+
+| | |
+|---|---|
+| **是什么** | 审计、修复、更新 coding agent 加载的 skill |
+| **形态** | CLI · OpenCode 插件（1.x / 2.x）· MCP server（Claude Code、Codex、DSH…） |
+| **来源** | `.opencode/skills`、`.claude/skills`、`.agents/skills`、`opencode.json(c)` 配置、HTTP catalog |
+| **能查** | 同 ID 遮蔽、重复、超长描述、超大正文、每步 token 预算、陈旧 skill |
+| **能修** | 归档遮蔽定义（可逆）、隐藏低频 skill、catalog 同步并检测 drift |
+| **成本** | CLI 0 token；插件工具定义约 191/步，另有每会话一次预警 |
+| **要求** | Node ≥ 20，零运行时依赖 |
+| **质量** | 41 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
 
 ## 为什么需要它
 
@@ -38,6 +55,24 @@ npm link
 skills-doctor check
 ```
 
+跑出来大概是这样：
+
+```text
+skills-doctor 0.3.11
+  来源: 5 个（存在 2 个）  定义: 29  唯一 ID: 29  会展示: 29  描述预算: ~3074 tokens
+
+[E] token-budget   模型每步要看到的 skill 描述约 3074 tokens，超过预算 1200 的 2 倍
+[W] long-description  "deep-research" 的 description 有 917 字符，每个模型步骤都会占上下文
+[W] large-body     "academic-paper" 正文约 9980 tokens，被调用时会整段塞进上下文
+...
+
+1 error, 18 warn, 0 info
+
+建议:
+  - 精简 description，或把低频 skill 设为 metadata.opencode/autoinvoke: false 隐藏。
+  - 正文拆到 references/，SKILL.md 只保留流程。
+```
+
 ## 命令
 
 所有命令都支持 `--lang en|zh`（默认按系统 locale 自动选择）和 `--json`。
@@ -95,6 +130,19 @@ skills-doctor update --into .\team-skills
 - 再跑一次 `update` 会自动重下被改坏的文件（drift 自愈）；
 - 用 `--prune` 删除 catalog 中已下架的 skill（默认只提示、不删）。
 
+## 插件到底费不费 token？
+
+本地执行不花 token，但注册给模型的工具每次请求都会带上定义。本仓库实测：
+
+| 项 | token | 何时产生 |
+|---|---|---|
+| 扫描 / 检测 / 修复 / 更新（本地） | **0** | 始终 |
+| `skills_doctor` 工具定义 | **约 191** | 每次请求 |
+| 注入系统提示的预算预警 | **约 60–80** | 每会话一次，且仅在超标时 |
+| 工具返回的审计报告 | **约 940** | 仅真正调用工具时 |
+
+所以插件是用固定的少量开销，换「模型能自己体检」。上面的例子里 skill 描述每步 3074 tokens，压到 1200 预算能省下 10 倍于插件开销的 token。想要**零上下文成本**，就别装插件——用 `npx opencode-skills-doctor check` 在终端或 CI 里跑。
+
 ## 配置
 
 在工作目录放一个可选的 `.skills-doctor.json`（或用 `--config <file>` 指定）：
@@ -157,6 +205,26 @@ export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"
 
 > 包根入口是 V2 插件，需要 OpenCode 2.x；CLI 两条线都能用。
 
+### 一键深度集成
+
+```powershell
+npx opencode-skills-doctor install
+```
+
+安装器会自动识别 OpenCode 版本并接好：
+
+- **2.x** —— 在 `opencode.json(c)` 里加 `"plugins": ["opencode-skills-doctor"]`；
+- **1.x** —— 把包装进 `~/.config/opencode`、写本地插件入口、生成 `/skills-doctor` 命令、补 `"type": "module"`；
+- 改配置前会备份为 `<config>.bak-<timestamp>`。
+
+支持 `--dry-run` 预览、`--config-dir <dir>` 指定配置目录、`--no-npm` 跳过装包。
+
+装好后你会得到：
+
+- `skills_doctor` 工具；
+- `/skills-doctor` 命令（1.x 是生成的 markdown 命令，2.x 是插件命令）；
+- 当 skill 描述预算超标时，系统提示里会注入一次提醒（每个会话最多一次）。
+
 ## MCP server（Claude Code、Codex、Kimi Code、任何 MCP 客户端）
 
 `skills-doctor mcp` 用 stdio 讲 Model Context Protocol，只暴露一个工具：`skills_doctor`，参数 `directory?`、`budget?`、`lang?`、`global?`。不需要装 OpenCode。
@@ -201,6 +269,29 @@ DSH 自带 MCP 客户端 bundle（`@deepseek-ai/dsh-mcp-client`）。在 profile
 
 Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`。
 
+## 工作原理
+
+**审计流程**
+
+1. 发现所有 skill 来源（见下面的优先级列表）。
+2. 解析每个 `SKILL.md` / 扁平 `.md` 的 frontmatter，估算描述与正文成本。
+3. 解析每个 ID 实际生效的定义（注册越后越优先；同序时 `SKILL.md` 目录形式优先）。
+4. 跑规则、计算每步 token 预算，输出 finding 与修复建议。
+
+**修复流程**
+
+`fix` 只动「被遮蔽、永远不会加载」的定义：把它们移到同一来源下的 `.skills-doctor-archive/<时间戳>/`。生效版本永远不会被移动，`update` 管理的文件会跳过。默认只处理项目内，`--all` 才扩展到全局来源。
+
+**更新流程**
+
+1. 抓 `<catalog>/index.json`（5xx/网络错误重试 3 次）。
+2. 对比每个 skill 的 `version` 与 lockfile。
+3. 下载变化的文件（仅同源、阻断路径穿越），原子写入。
+4. 删除新版本不再包含的文件，清理空目录。
+5. 校验哈希、写 lockfile；加 `--prune` 时删除已从 catalog 下架的 skill。
+
+`check` 会读 lockfile，报告 drift（`managed-drift`）、文件缺失（`managed-missing`）和未知 lock 版本（`lock-version-unsupported`）；再跑一次 `update` 会重下被改坏的文件。
+
 ## 检测规则
 
 | 规则 | 级别 | 含义 |
@@ -277,17 +368,61 @@ Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c",
 - `check` 不联网；要看 catalog 新版本用 `update --check-only`。
 - 配置优先级假设：全局配置 < 项目配置 < `skills` 数组顺序。
 
+## 常见问题（FAQ）
+
+**我建的 skill 没出现。**
+依次检查：有没有 `description`？是不是被 `opencode/autoinvoke: false` 或 `disable-model-invocation` 隐藏了？ID 是否按路径推导（目录形式取目录名，扁平 `.md` 取文件名）？是不是被别的来源遮蔽了？跑 `skills-doctor scan` 能看到每个 ID 实际生效的是哪份。
+
+**`fix` 跑了但什么都没变。**
+`fix` 只归档**被遮蔽**的重复定义，而且默认只处理项目内。先 `skills-doctor fix --dry-run` 看会做什么；要动全局加 `--all`。描述过长、正文过大属于内容问题，只报告、不自动改写。
+
+**`check` 说预算超标，但用起来没感觉。**
+token 是启发式估算，1200 是建议预算。可以用 `--budget` 或 `.skills-doctor.json` 调整；把它当相对比较，不是账单。
+
+**`fix` 把我的文件挪到哪了？**
+同一 skill 来源下的 `.skills-doctor-archive/<时间戳>/`，移回去即可恢复。
+
+**会在后台自动更新 skill 吗？**
+没有常驻进程。想同步时跑 `skills-doctor update`；只想看有没有新版本用 `--check-only`。
+
+**支持 OpenCode 1.x 吗？**
+支持。CLI 两条线都能用；`skills-doctor install` 会给 1.x 写本地插件入口并生成命令文件（1.x 没有插件注册命令的 API）。
+
+**本地插件为什么还费 token？**
+执行代码免费，但工具定义会进模型上下文。这也是保留 CLI 模式的原因：零上下文成本。
+
 ## Roadmap
 
 - v0.4：内容层面的建议（哪些 skill 从未被使用）、catalog 签名校验
 - 后续：V1/Claude skill 兼容迁移报告
 
-## 开发
+## 开发与贡献
 
 ```powershell
-npm test
+npm test          # 41 个测试（node test/doctor.test.mjs）
+npm run bench     # 100/500/1000 个 skill 的 lint 耗时
 ```
 
-测试覆盖：frontmatter 解析、来源发现与优先级、遮蔽/重复/预算规则、catalog 下载与 lock、drift 检测与自愈、旧/新 lock 的向上兼容、CLI JSON 与退出码。
+- CI 跑 ubuntu/macos/windows × Node 20/22/24；`prepublishOnly` 会在每次发布前重跑测试。
+- 欢迎 issue 和 PR：行为改动请先开 issue 说明场景与期望输出，PR 里关联该 issue。
+- 两条不变量：CLI 保持零依赖；输出保持中英双语（`--lang en|zh`）。
+- 安全问题请看 [SECURITY.zh-CN.md](../SECURITY.zh-CN.md)，不要开公开 issue。
+- 版本记录见 [CHANGELOG.md](../CHANGELOG.md)。
+
+### 目录结构
+
+| 路径 | 作用 |
+|---|---|
+| `src/audit.mjs` | 一次完整审计（CLI / 插件 / MCP 共用） |
+| `src/discover.mjs` | 来源发现、优先级、JSONC 解析 |
+| `src/lint.mjs` | 规则、token 预算、近似描述检测 |
+| `src/fix.mjs` | 归档 / hide |
+| `src/catalog.mjs` | 更新器、lockfile、重试、原子写入 |
+| `src/managed.mjs` | lock 校验与 drift 检测 |
+| `src/cli.mjs` | 命令分发与输出 |
+| `src/i18n.mjs` | 中英文案 |
+| `src/mcp.mjs` | MCP stdio server |
+| `src/plugin.mjs` / `src/plugin-v1.mjs` | OpenCode 2.x / 1.x 入口 |
+| `src/install.mjs` | 一键接入 OpenCode |
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Audit, fix and update agent skills: per-step context cost, shadowed duplicates, safe archive, catalog sync. CLI, OpenCode plugin and MCP server (Claude Code / Codex / any MCP client).",
   "type": "module",
   "exports": {

package/src/cli.mjs

@@ -8,6 +8,7 @@ import { planFixes, applyFixes, hideSkills } from "./fix.mjs"
 import { auditSkills } from "./audit.mjs"
 import { loadConfig } from "./config.mjs"
 import { startMcpServer } from "./mcp.mjs"
+import { installOpenCode } from "./install.mjs"
 import { padDisplay } from "./parse.mjs"
 import { detectLang, normalizeLang, translator } from "./i18n.mjs"
 
@@ -56,12 +57,14 @@ function parseArgs(argv) {
     into: null,
     checkOnly: false,
     prune: false,
+    configDir: null,
+    noNpm: false,
     help: false,
     version: false,
   }
 
   const args = [...argv]
-  const commands = new Set(["check", "scan", "update", "fix", "mcp", "help"])
+  const commands = new Set(["check", "scan", "update", "fix", "install", "mcp", "help"])
   if (args[0] && commands.has(args[0])) {
     options.command = args.shift()
   }
@@ -116,6 +119,12 @@ function parseArgs(argv) {
       case "--prune":
         options.prune = true
         break
+      case "--config-dir":
+        options.configDir = path.resolve(args[++i] ?? ".")
+        break
+      case "--no-npm":
+        options.noNpm = true
+        break
       case "-h":
       case "--help":
         options.help = true
@@ -444,6 +453,28 @@ export async function main(argv) {
     return
   }
 
+  if (options.command === "install") {
+    const result = installOpenCode({
+      configDir: options.configDir ?? undefined,
+      dryRun: options.dryRun,
+      installPackage: !options.noNpm,
+    })
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2))
+    } else {
+      console.log(bold(t("install.title")))
+      console.log(dim(t("install.version", { version: result.version ?? "unknown" })))
+      console.log(dim(t("install.configDir", { dir: result.configDir })))
+      if (result.dryRun) console.log(dim(t("install.dryRun")))
+      for (const action of result.actions) console.log(`  · ${action}`)
+      for (const error of result.errors) console.log(red(t("install.error", { error })))
+      console.log("")
+      console.log(result.errors.length ? red(t("install.failed")) : dim(t("install.next")))
+    }
+    process.exitCode = result.errors.length ? 1 : 0
+    return
+  }
+
   if (options.command === "check") {
     const audit = auditSkills({
       cwd,

package/src/i18n.mjs

@@ -10,6 +10,7 @@ Usage:
   skills-doctor scan   [options]   list every skill with its source and precedence
   skills-doctor fix    [options]   archive shadowed definitions (safe structural fixes)
   skills-doctor update [options]   compare and download skills from HTTP catalogs
+  skills-doctor install [options]  wire the plugin into OpenCode (1.x / 2.x)
   skills-doctor mcp                run as an MCP server (Claude Code, Codex, any MCP client)
 
 Options:
@@ -27,6 +28,8 @@ Options:
   --into <dir>         update: output directory (default: .opencode/skills)
   --check-only         update: only report available updates
   --prune              update: delete skills that disappeared from the catalog
+  --config-dir <dir>   install: OpenCode config directory (default: ~/.config/opencode)
+  --no-npm             install: do not run npm install (1.x)
   -h, --help           show this help
   -v, --version        print version
 
@@ -74,6 +77,13 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "update.pruned": "  · pruned {count} skills no longer in the catalog: {names}",
     "update.orphaned": "  ! {count} skills are no longer in the catalog (use --prune to delete them)",
     "update.lock": "  lock: {path} ({name})",
+    "install.title": "OpenCode integration",
+    "install.version": "  OpenCode: {version}",
+    "install.configDir": "  config dir: {dir}",
+    "install.dryRun": "  (dry run: nothing is written)",
+    "install.error": "  ✗ {error}",
+    "install.failed": "Integration failed.",
+    "install.next": "Restart OpenCode to activate.",
     "update.lockTooNew": "  ! lock is newer than this tool; parsed in compatibility mode (unknown fields ignored)",
     "update.detector": "  check now sees these skills ({dir} is where opencode reads)",
     "update.noCatalogs": "No HTTP catalog configured. Add https://... to the skills array in opencode.json(c).",
@@ -156,6 +166,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   skills-doctor scan   [选项]   列出所有 skill 及其来源/优先级
   skills-doctor fix    [选项]   归档被遮蔽的定义（安全的结构性修复）
   skills-doctor update [选项]   对比并拉取 HTTP catalog 里的 skill
+  skills-doctor install [选项]  把插件接入 OpenCode（1.x / 2.x）
   skills-doctor mcp            以 MCP server 方式运行（Claude Code、Codex 等任何 MCP 客户端）
 
 选项:
@@ -173,6 +184,8 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   --into <dir>        update 的落盘目录（默认 .opencode/skills）
   --check-only        update 只报告可用更新，不下载
   --prune             update: 删除 catalog 中已移除的 skill
+  --config-dir <dir>  install: OpenCode 配置目录（默认 ~/.config/opencode）
+  --no-npm            install: 不执行 npm install（1.x）
   -h, --help          帮助
   -v, --version       版本
 
@@ -220,6 +233,13 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "update.pruned": "  · 清理 catalog 中已移除的 skill {count} 个: {names}",
     "update.orphaned": "  ! {count} 个 skill 已不在 catalog 中（加 --prune 可删除本地残留）",
     "update.lock": "  lock: {path}（{name}）",
+    "install.title": "OpenCode 集成",
+    "install.version": "  OpenCode: {version}",
+    "install.configDir": "  配置目录: {dir}",
+    "install.dryRun": "  （dry run：不会写入任何内容）",
+    "install.error": "  ✗ {error}",
+    "install.failed": "集成失败。",
+    "install.next": "重启 OpenCode 生效。",
     "update.lockTooNew": "  ! lock 版本比本工具新，已按兼容模式解析（未知字段忽略）",
     "update.detector": "  check 现在可以直接检测到这些 skill（{dir} 是 opencode 会读取的目录）",
     "update.noCatalogs": "没有配置 HTTP catalog。在 opencode.json(c) 的 skills 数组里写 https://... 即可。",

package/src/install.mjs

@@ -0,0 +1,211 @@
+import fs from "node:fs"
+import path from "node:path"
+import os from "node:os"
+import { spawnSync, execFileSync } from "node:child_process"
+import { stripJsonc } from "./discover.mjs"
+
+export const PACKAGE_NAME = "opencode-skills-doctor"
+const PLUGIN_FILE = "skills-doctor.js"
+const COMMAND_FILE = "skills-doctor.md"
+
+const V1_PLUGIN_SOURCE = `// Generated by skills-doctor install\n// OpenCode 1.x plugin entry\nexport { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"\n`
+
+const V1_COMMAND = `---
+description: Audit local skills with skills-doctor
+---
+Use the skills_doctor tool to audit the skills in this project. Summarize the top findings and propose concrete fixes (archive shadowed duplicates, hide low-frequency skills). $ARGUMENTS
+`
+
+export function defaultConfigDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config")
+  return path.join(base, "opencode")
+}
+
+function readJsonc(file) {
+  return JSON.parse(stripJsonc(fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "")))
+}
+
+function writeJson(file, data) {
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n", "utf8")
+}
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "")
+  } catch {
+    return null
+  }
+}
+
+function detectVersion() {
+  try {
+    const out = execFileSync("opencode", ["--version"], { encoding: "utf8", timeout: 15000 })
+    const match = /(\d+)\.(\d+)\.(\d+)/.exec(String(out))
+    if (match) return match[0]
+  } catch {}
+  return null
+}
+
+function configFile(dir) {
+  const candidates = ["opencode.jsonc", "opencode.json"]
+    .map((name) => path.join(dir, name))
+    .filter((file) => fs.existsSync(file))
+
+  // 优先沿用已经在配置 plugin/plugins 的文件，避免把插件写进另一个配置文件后被覆盖
+  for (const file of candidates) {
+    try {
+      const config = readJsonc(file)
+      if (config.plugin !== undefined || config.plugins !== undefined) return file
+    } catch {}
+  }
+
+  return candidates[0] ?? path.join(dir, "opencode.json")
+}
+
+function backup(file, stamp) {
+  if (!fs.existsSync(file)) return null
+  const target = `${file}.bak-${stamp}`
+  fs.copyFileSync(file, target)
+  return target
+}
+
+function ensureUniqueEntry(list, entry) {
+  if (!Array.isArray(list)) return [entry]
+  return list.includes(entry) ? list : [...list, entry]
+}
+
+function installPackage(dir) {
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm"
+  const result = spawnSync(npm, ["install", "--prefix", dir, PACKAGE_NAME + "@latest", "--no-audit", "--no-fund"], {
+    stdio: "inherit",
+    env: process.env,
+    timeout: 180000,
+  })
+  return result.status === 0
+}
+
+/**
+ * 把 skills-doctor 装进 OpenCode：
+ * - 2.x：写入 plugins 数组（OpenCode 自己从 npm 拉包）
+ * - 1.x：在配置目录安装包、写本地插件入口、写 /skills-doctor 命令、补插件数组
+ */
+export function installOpenCode({ configDir = defaultConfigDir(), version = null, dryRun = false, installPackage: withPackage = true } = {}) {
+  const dir = path.resolve(configDir)
+  const actions = []
+  const errors = []
+  const dry = (message) => actions.push(`[dry-run] ${message}`)
+  const act = (message) => actions.push(message)
+
+  const cfgFile = configFile(dir)
+  const existingText = readText(cfgFile)
+  let config = {}
+  if (existingText !== null) {
+    try {
+      config = readJsonc(cfgFile)
+    } catch (err) {
+      errors.push(`cannot parse ${cfgFile}: ${err.message}`)
+      return { version, major: null, configDir: dir, configFile: cfgFile, actions, errors, dryRun }
+    }
+  }
+
+  const resolvedVersion = version ?? detectVersion()
+  const inferredMajor = config.plugin !== undefined ? 1 : 2
+  const major = resolvedVersion ? Number(resolvedVersion.split(".")[0]) : inferredMajor
+
+  if (dryRun) dry(`config dir: ${dir}`)
+  if (!fs.existsSync(dir)) {
+    if (!dryRun) fs.mkdirSync(dir, { recursive: true })
+    act(`created config dir ${dir}`)
+  }
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-")
+
+  if (major >= 2) {
+    const next = { ...config, plugins: ensureUniqueEntry(config.plugins, PACKAGE_NAME) }
+    const changed = !Array.isArray(config.plugins) || !config.plugins.includes(PACKAGE_NAME)
+    if (changed) {
+      if (!dryRun) {
+        const backupFile = backup(cfgFile, stamp)
+        if (backupFile) act(`backup ${backupFile}`)
+        writeJson(cfgFile, next)
+        act(`added "${PACKAGE_NAME}" to plugins in ${cfgFile}`)
+      } else dry(`add "${PACKAGE_NAME}" to plugins in ${cfgFile}`)
+    } else {
+      act(`plugins already contains "${PACKAGE_NAME}"`)
+    }
+    act("restart OpenCode; the /skills-doctor command and skills_doctor tool will be available")
+    return { version: resolvedVersion, major, configDir: dir, configFile: cfgFile, actions, errors, dryRun }
+  }
+
+  // 1.x
+  const pluginFile = path.join(dir, "plugins", PLUGIN_FILE)
+  const commandFile = path.join(dir, "command", COMMAND_FILE)
+  const pluginPath = pluginFile
+
+  const hasPackage = fs.existsSync(path.join(dir, "node_modules", PACKAGE_NAME, "package.json"))
+  if (!hasPackage) {
+    if (withPackage && !dryRun) {
+      act(`installing ${PACKAGE_NAME} into ${dir}`)
+      if (!installPackage(dir)) errors.push(`npm install failed for ${PACKAGE_NAME}`)
+      else act(`installed ${PACKAGE_NAME}`)
+    } else if (dryRun) {
+      dry(`install ${PACKAGE_NAME} into ${dir}`)
+    } else {
+      act(`skipped npm install; run: npm i --prefix "${dir}" ${PACKAGE_NAME}`)
+    }
+  } else {
+    act(`${PACKAGE_NAME} already installed in ${dir}`)
+  }
+
+  if (!fs.existsSync(pluginFile)) {
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(pluginFile), { recursive: true })
+      fs.writeFileSync(pluginFile, V1_PLUGIN_SOURCE, "utf8")
+      act(`wrote plugin entry ${pluginFile}`)
+    } else dry(`write plugin entry ${pluginFile}`)
+  } else {
+    act(`plugin entry already exists ${pluginFile}`)
+  }
+
+  if (!fs.existsSync(commandFile)) {
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(commandFile), { recursive: true })
+      fs.writeFileSync(commandFile, V1_COMMAND, "utf8")
+      act(`wrote command ${commandFile}`)
+    } else dry(`write command ${commandFile}`)
+  } else {
+    act(`command already exists ${commandFile}`)
+  }
+
+  const nextPlugin = ensureUniqueEntry(config.plugin, pluginPath)
+  const pluginChanged = !Array.isArray(config.plugin) || !config.plugin.includes(pluginPath)
+  if (pluginChanged) {
+    if (!dryRun) {
+      const backupFile = backup(cfgFile, stamp)
+      if (backupFile) act(`backup ${backupFile}`)
+      writeJson(cfgFile, { ...config, plugin: nextPlugin })
+      act(`added plugin entry to ${cfgFile}`)
+    } else dry(`add plugin entry to ${cfgFile}`)
+  } else {
+    act("plugin array already configured")
+  }
+
+  const pkgFile = path.join(dir, "package.json")
+  const pkgText = readText(pkgFile)
+  let pkg = {}
+  if (pkgText !== null) {
+    try {
+      pkg = JSON.parse(pkgText)
+    } catch {}
+  }
+  if (pkg.type !== "module") {
+    if (!dryRun) {
+      pkg.type = "module"
+      fs.writeFileSync(pkgFile, JSON.stringify(pkg, null, 2) + "\n", "utf8")
+      act(`set "type": "module" in ${pkgFile}`)
+    } else dry(`set "type": "module" in ${pkgFile}`)
+  }
+
+  act("restart OpenCode; the skills_doctor tool and /skills-doctor command will be available")
+  return { version: resolvedVersion, major, configDir: dir, configFile: cfgFile, actions, errors, dryRun }
+}

package/src/plugin-v1.mjs

@@ -1,5 +1,6 @@
 import { tool } from "@opencode-ai/plugin"
 import { auditSkills, formatMarkdown } from "./audit.mjs"
+import { budgetWarning } from "./warning.mjs"
 
 const z = tool.schema
 
@@ -25,6 +26,10 @@ export const SkillsDoctorPlugin = async ({ directory }) => ({
       },
     }),
   },
+  "experimental.chat.system.transform": async (input, output) => {
+    const warning = budgetWarning({ cwd: directory, sessionID: input?.sessionID })
+    if (warning) output.system.push(warning)
+  },
 })
 
 export const server = SkillsDoctorPlugin

package/src/plugin.mjs

@@ -1,5 +1,6 @@
 import { Plugin } from "@opencode/plugin"
 import { auditSkills, formatMarkdown } from "./audit.mjs"
+import { budgetWarning } from "./warning.mjs"
 
 /**
  * OpenCode 插件入口：把 skills-doctor 暴露成 skills_doctor 工具和 /skills-doctor 命令。
@@ -48,5 +49,11 @@ export default Plugin.define({
         },
       })
     })
+
+    // 每个会话最多注入一次预算预警，避免刷屏
+    await ctx.session.hook("context", (event) => {
+      const warning = budgetWarning({ cwd: ctx.location.directory, sessionID: event.sessionID })
+      if (warning) event.system.push({ type: "text", text: warning })
+    })
   },
 })

package/src/warning.mjs

@@ -0,0 +1,37 @@
+import { auditSkills } from "./audit.mjs"
+
+const cache = new Map()
+const warned = new Set()
+
+/**
+ * 每个会话最多注入一次「skill 预算超标」提醒。
+ * 只在存在 error（默认预算超标 2 倍）时提醒，避免刷屏。
+ */
+export function budgetWarning({ cwd = process.cwd(), sessionID = "global", ttlMs = 60000, includeGlobal = true } = {}) {
+  const key = `${cwd}::${sessionID}`
+  if (warned.has(key)) return null
+
+  const now = Date.now()
+  let entry = cache.get(cwd)
+  if (!entry || now - entry.at > ttlMs) {
+    const audit = auditSkills({ cwd, includeGlobal })
+    const over = audit.counts.errors > 0
+    entry = {
+      at: now,
+      text: over
+        ? `[skills-doctor] ${audit.summary.unique} skills use ~${audit.summary.advertisedTokens} tokens of descriptions per step (budget ${audit.budget}); ${audit.counts.errors} error(s), ${audit.counts.warnings} warning(s). Use the skills_doctor tool for details, then hide low-frequency skills with \`skills-doctor fix --hide <ids>\`.`
+        : null,
+    }
+    cache.set(cwd, entry)
+  }
+
+  if (!entry.text) return null
+  warned.add(key)
+  return entry.text
+}
+
+/** 测试用：清空缓存与已提醒集合。 */
+export function resetWarningState() {
+  cache.clear()
+  warned.clear()
+}