opencode-skills-doctor 0.9.4 → 0.9.7

package/README.md

@@ -5,8 +5,8 @@
 <h1 align="center">skills-doctor</h1>
 
 <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.
+  <b>Your skills are quietly taxing every single step.</b><br>
+  29 skills = ~3,074 tokens burned before the model even sees your code.
 </p>
 
 <p align="center">
@@ -14,6 +14,7 @@
   <a href="https://www.npmjs.com/package/opencode-skills-doctor"><img src="https://img.shields.io/npm/dw/opencode-skills-doctor?style=for-the-badge&color=2ea043" alt="npm downloads"></a>
   <a href="https://github.com/wangyuchen5110/opencodeplugginprogram/stargazers"><img src="https://img.shields.io/github/stars/wangyuchen5110/opencodeplugginprogram?style=for-the-badge&color=58a6ff" alt="GitHub stars"></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" alt="tests"></a>
+  <a href="https://github.com/marketplace/actions/skills-doctor"><img src="https://img.shields.io/badge/GitHub%20Marketplace-skills--doctor-3fb950?style=for-the-badge&logo=github" alt="GitHub Marketplace"></a>
 </p>
 
 <p align="center">
@@ -31,25 +32,27 @@
 > **Runs 100% locally.** No telemetry, no account, no uploads — your skills,
 > prompts and files never leave your machine. See [Privacy](#privacy-local-only-no-data-collection).
 
-## Contents
+## The hidden tax
 
-- [The 30-second version](#the-30-second-version) · [Privacy](#privacy-local-only-no-data-collection)
-- [See it](#see-it) · [How it works](#how-it-works) · [Quick start](#quick-start)
-- [Install](#install) · [Use it in CI](#use-it-in-ci-github-action) · [Commands](#commands) · [Works where you work](#works-where-you-work)
-- [Why it is safe](#why-it-is-safe) · [Development](#development)
+Every agent skill with a `description` is injected into the system prompt on **every single step**. On a real machine with 29 skills that was **~3,074 tokens** — before the model read a single line of code. Duplicates silently shadow each other. Long descriptions never get trimmed. Broken references go unnoticed.
 
-## The 30-second version
+`skills-doctor` measures the exact cost, shows which definition actually wins, and gives you a concrete plan to cut it:
 
-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.
+```text
+current: ~3,124 tokens/step (30 advertised)   budget: 1,200
+
+Recommended: trim 26 + hide 2 → 1,184 tokens/step  (−1,940)
+Over 100 steps that saves ~194,000 tokens.
+```
 
-`skills-doctor` measures that cost, shows which definition actually wins, and fixes it:
+One command. Runs 100% locally. No account, no telemetry, nothing leaves your machine.
 
 | | |
 |---|---|
 | **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 |
+| **Fix** | archive shadowed definitions (reversible), hide redundant skills before unique ones, keep the routing sentence in the plan |
 | **Update** | sync skills from HTTP catalogs with a lockfile, drift detection and `--prune` |
-| **Report** | terminal, JSON, or a self-contained HTML report |
+| **Report** | a short note in the OpenCode chat, plus the terminal and JSON |
 | **Run it** | CLI · OpenCode plugin (1.x/2.x/Desktop) · MCP server · DeepSeek Harness skill |
 
 ## Privacy: local-only, no data collection
@@ -62,17 +65,13 @@ Every agent skill with a `description` is advertised to the model on **every sin
 | **Never reads** | conversation history, session transcripts, source code, documents, credentials, API keys or environment secrets |
 | **Uploads** | nothing: there is no server component and no remote endpoint besides the two optional calls below |
 | **Network** | only when you ask for it. `update` fetches the HTTP catalogs **you** configure; `upgrade` / the daily update check reads the npm registry for the latest version number (cached 24 h — disable with `"checkUpdates": "off"`, `SKILLS_DOCTOR_UPDATE_CHECK=0` or `--no-update-check`) |
-| **Writes** | only what you asked for: the HTML/JSON report, `.skills-doctor-archive/`, `.skills-doctor.json`, the lockfile, and the plugin/MCP/skill entries created by `install` |
+| **Writes** | only what you asked for: `.skills-doctor-archive/`, `.skills-doctor.json`, the lockfile, and the plugin/MCP/skill entries created by `install` |
 
 `opencode.json(c)` and MCP configs can contain credentials; they are parsed locally only to find the relevant entries, and those values are never sent anywhere nor included in a report. Reports contain file paths and skill descriptions (which are part of your skill files), never file bodies. `check`, `plan`, `scan`, `fix --dry-run` and `mcp` all work with the network fully offline.
 
-## See it
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/wangyuchen5110/opencodeplugginprogram/main/docs/assets/report.png" alt="skills-doctor HTML report" width="82%">
-</p>
+## What you see
 
-A real `check --html` run: summary cards, the context-budget bar, filterable findings, and the exact potential savings.
+In OpenCode 2, the first message of a session gets one notice in the chat when a skill is over budget, shadowed, or broken. It names at most three problems and does not change any file. `/skills-doctor` posts that notice again. The terminal `check` and `--json` output stay for CI.
 
 ## How it works
 
@@ -83,7 +82,7 @@ flowchart LR
   C --> D["lint<br/>16 rules + token budget"]
   D --> E{"findings?"}
   E -->|"yes"| F["plan / fix<br/>trim · hide · archive"]
-  E -->|"always"| G["report<br/>terminal · JSON · HTML"]
+  E -->|"always"| G["tell you<br/>chat · terminal · JSON"]
   F --> G
   G --> H["you · CI · the agent"]
 ```
@@ -99,26 +98,12 @@ npx -y opencode-skills-doctor check
 
 # how many tokens can I actually cut?
 npx -y opencode-skills-doctor plan
-
-# shareable HTML report
-npx -y opencode-skills-doctor check --html report.html --open
-```
-
-Example `plan` output on a real setup:
-
-```text
-current: ~3,124 tokens/step (30 advertised)   budget: 1,200
-
-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
 ```
 
 ## Install
 
 ```powershell
-# OpenCode — plugin + /skills-doctor, /skills-report, /skills-upgrade commands
+# OpenCode — plugin + /skills-doctor and /skills-upgrade
 npx -y opencode-skills-doctor install              # auto-detects 1.x / 2.x / Desktop
 npx -y opencode-skills-doctor install --client desktop
 
@@ -141,7 +126,8 @@ Nothing to configure for **skills discovery**: it reads `.opencode/skills`, `.cl
 ## Use it in CI (GitHub Action)
 
 A composite action ships in this repo: no install step, no runtime dependencies —
-it runs the checked-out code directly.
+it runs the checked-out code directly. It is listed on the
+[GitHub Marketplace](https://github.com/marketplace/actions/skills-doctor).
 
 ```yaml
 name: skills
@@ -156,16 +142,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: wangyuchen5110/opencodeplugginprogram@v0.9.4
+      - uses: wangyuchen5110/opencodeplugginprogram@v0.9.7
         with:
           budget: "1200"
           fail-on: warn             # error | warn | never
-          html: skills-report.html  # written and uploaded as an artifact
           comment: "true"           # post the summary on the PR
 ```
 
-It writes a summary to the job page, uploads the HTML report, optionally comments
-on the pull request, and fails the job according to `fail-on`.
+It writes a summary to the job page, optionally comments on the pull request,
+and fails the job according to `fail-on`.
 
 | Input | Default | Purpose |
 |---|---|---|
@@ -173,7 +158,6 @@ on the pull request, and fails the job according to `fail-on`.
 | `budget` | `1200` | Description tokens paid per model step |
 | `fail-on` | `error` | Fail on `error`, `warn`, or `never` |
 | `extra-args` | — | Extra `check` flags, e.g. `--no-global` |
-| `html` | — | HTML report path; uploaded as an artifact when set |
 | `comment` | `false` | Post/append the summary as a pull request comment |
 
 Outputs: `exit-code`, `error-count`, `warning-count`, `advertised-tokens`.
@@ -183,7 +167,7 @@ Outputs: `exit-code`, `error-count`, `warning-count`, `advertised-tokens`.
 | 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 |
+| `plan` | savings from keeping the first sentence, then hiding redundant skills first, 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 |
@@ -204,7 +188,7 @@ All commands accept `--json`, `--lang en|zh`, `--budget`, `--root` and `--no-glo
 | **Claude Code / Codex** | MCP server (`npx -y opencode-skills-doctor mcp`) |
 | **Grok CLI / Cursor** | their skill roots are scanned natively |
 | **Hermes Agent** | MCP entry in `~/.hermes/config.yaml`; `~/.hermes/skills` is scanned |
-| **Kimi Code** | `install --client kimi` writes `~/.kimi-code/mcp.json` + the audit skill |
+| **Kimi Code** | `install --client kimi` writes `~/.kimi-code/mcp.json` + the audit skill; or use the native plugin: [kimi-skills-doctor](https://github.com/wangyuchen5110/kimi-skills-doctor) |
 | **OpenClaw** | separate wrapper with its own native plugin: [openclaw-skills-doctor](https://github.com/wangyuchen5110/openclaw-skills-doctor) |
 
 ## Why it is safe
@@ -217,7 +201,7 @@ All commands accept `--json`, `--lang en|zh`, `--budget`, `--root` and `--no-glo
 ## Development
 
 ```powershell
-npm test          # 58 tests (node test/doctor.test.mjs)
+npm test          # 73 tests (node test/doctor.test.mjs)
 npm run bench     # lint timing for 100/500/1000 skills
 ```
 

package/SECURITY.md

@@ -33,7 +33,7 @@ Include the version, a reproduction, the impact, and a suggested fix if you have
 - **No network by default.** Two opt-in/opt-out exceptions: `update` fetches the catalog URLs you configure, and the daily update check reads only the latest version number from the npm registry (24 h cache; disable with `"checkUpdates": "off"`, `SKILLS_DOCTOR_UPDATE_CHECK=0` or `--no-update-check`).
 - **No user data is read.** The tool reads skill files, their referenced resources, agent configuration and its own lockfile. It does not read chat history, session transcripts, source code, documents, model credentials or API keys — and it does not upload anything it reads.
 - **Config files may hold secrets** (`opencode.json(c)`, MCP configs). They are parsed locally only to locate the entries the tool needs; values are never transmitted, printed, or copied into reports.
-- **Reports are local files.** HTML/JSON reports contain file paths and skill descriptions, never file bodies. They can reveal your directory layout, so review them before sharing.
+- **Reports stay on the machine.** Terminal output, JSON, the pull-request comment and the chat notice contain file paths and skill descriptions, never file bodies. They can reveal your directory layout, so review them before sharing.
 - `check`, `plan`, `scan`, `fix --dry-run` and `mcp` are fully offline; you can run them with networking disabled.
 
 ## Risk areas and mitigations

package/SECURITY.zh-CN.md

@@ -33,7 +33,7 @@
 - **默认不联网。** 只有两个例外：`update` 抓取你配置的 catalog URL；每日更新检查只从 npm registry 读取最新版本号（缓存 24h，可用 `"checkUpdates": "off"`、`SKILLS_DOCTOR_UPDATE_CHECK=0` 或 `--no-update-check` 关闭）。
 - **不读取用户数据。** 只读 skill 文件及其引用资源、agent 配置和自身 lockfile；不读对话历史、会话记录、源代码、文档、模型凭据或 API key，也不上传任何读到的内容。
 - **配置文件可能含密钥**（`opencode.json(c)`、MCP 配置）：只在本地解析以定位需要的条目，值不会被传输、打印或写进报告。
-- **报告是本地文件。** HTML/JSON 报告含文件路径和 skill 描述，不含文件正文；可能暴露目录结构，分享前请自行检查。
+- **报告留在本机。** 终端输出、JSON、PR 评论和对话通知含文件路径和 skill 描述，不含文件正文；可能暴露目录结构，分享前请自行检查。
 - `check`、`plan`、`scan`、`fix --dry-run`、`mcp` 完全离线，可在断网环境运行。
 
 ## 风险点与缓解措施

package/docs/README.zh-CN.md

@@ -5,8 +5,8 @@
 <h1 align="center">skills-doctor</h1>
 
 <p align="center">
-  <b>审计、修复、更新你的 coding agent 加载的 skill。</b><br>
-  量出每步 token 税，找出遮蔽重复和断链，再安全地修掉。
+  <b>量出 coding agent 每一步为 skill 付出的 token。</b><br>
+  按词估算，丢掉套话重叠，方案只留路由用的第一句，并先藏重复的 skill。
 </p>
 
 <p align="center">
@@ -14,6 +14,7 @@
   <a href="https://www.npmjs.com/package/opencode-skills-doctor"><img src="https://img.shields.io/npm/dw/opencode-skills-doctor?style=for-the-badge&color=2ea043" alt="downloads"></a>
   <a href="https://github.com/wangyuchen5110/opencodeplugginprogram/stargazers"><img src="https://img.shields.io/github/stars/wangyuchen5110/opencodeplugginprogram?style=for-the-badge&color=58a6ff" alt="stars"></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" alt="tests"></a>
+  <a href="https://github.com/marketplace/actions/skills-doctor"><img src="https://img.shields.io/badge/GitHub%20Marketplace-skills--doctor-3fb950?style=for-the-badge&logo=github" alt="GitHub Marketplace"></a>
 </p>
 
 <p align="center">
@@ -47,10 +48,10 @@ OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **Open
 | **形态** | CLI · OpenCode 插件（1.x / 2.x）· MCP server（Claude Code、Codex、DSH…）· 兼容 Grok CLI |
 | **来源** | `.opencode/skills`、`.claude/skills`、`.agents/skills`、`.grok/skills`、`.cursor/skills`、`.hermes/skills`、`.kimi-code/skills`、`.dsh/skills`（含 `$DSH_HOME`）、`opencode.json(c)` 配置、HTTP catalog |
 | **能查** | 同 ID 遮蔽、重复、超长描述、超大正文、每步 token 预算、断链引用、非法 frontmatter、空正文、陈旧 skill |
-| **能修** | 归档遮蔽定义（可逆）、隐藏低频 skill、catalog 同步并检测 drift |
-| **报告** | 终端、JSON，或自包含 HTML（`--html [file] --open`） |
+| **能修** | 归档遮蔽定义（可逆）、先藏重复的 skill、方案只留路由用的第一句 |
+| **报告** | OpenCode 对话里的一条通知，加上终端和 JSON |
 | **规划** | 精确 token 节省：精简描述 / 隐藏 skill，按 N 步折算 |
-| **成本** | CLI 0 token；插件工具定义约 191/步，另有每会话一次预警 |
+| **成本** | CLI 0 token；有问题时每个会话在对话里发一条通知 |
 | **要求** | Node ≥ 20，零运行时依赖 |
 | **质量** | 63 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
 
@@ -64,7 +65,7 @@ OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **Open
 | **不会读** | 对话历史、会话记录、源代码、文档、凭据、API key、环境变量里的密钥 |
 | **不会上传** | 任何东西：没有服务端组件，除下面两个可选联网外没有任何远端地址 |
 | **联网** | 只在你主动触发时发生：`update` 抓取**你自己配置**的 HTTP catalog；`upgrade` / 每日更新检查只读 npm registry 的最新版本号（缓存 24h，可用 `"checkUpdates": "off"`、`SKILLS_DOCTOR_UPDATE_CHECK=0` 或 `--no-update-check` 关闭） |
-| **会写** | 只写你要求的内容：HTML/JSON 报告、`.skills-doctor-archive/`、`.skills-doctor.json`、lockfile，以及 `install` 生成的插件/MCP/skill 条目 |
+| **会写** | 只写你要求的内容：`.skills-doctor-archive/`、`.skills-doctor.json`、lockfile，以及 `install` 生成的插件/MCP/skill 条目 |
 
 `opencode.json(c)` 和 MCP 配置里可能有凭据；它们只在本地被解析用来定位相关条目，值不会被发送，也不会出现在报告里。报告只含文件路径和 skill 描述（本来就是你的 skill 文件内容），不包含正文。`check`、`plan`、`scan`、`fix --dry-run`、`mcp` 都可以在断网环境下运行。
 
@@ -131,20 +132,13 @@ skills-doctor check
 skills-doctor check --json
 skills-doctor check --budget 800 --strict    # CI 用
 skills-doctor check --root .\some-project --no-global
-skills-doctor check --html report.html       # 自包含 HTML 报告
-skills-doctor check --html report.html --open
 ```
 
-### HTML 报告
+### 对话通知
 
-`--html [file]` 生成单个自包含 HTML 文件（无外部资源）：
+OpenCode 2 在你发出第一条消息时，如果有 error 或 warning，就在对话里发一条通知。它是带描述 `skills-doctor` 的 synthetic 消息，会单独占一行，不会再开一轮模型。`/skills-doctor` 会再发一次，没有问题也会说。工具和 MCP 返回同一段短文，不写文件。最多列三条。归档和隐藏仍然要你确认。
 
-- 摘要卡片 + 上下文预算条；
-- 可按严重级别和文本过滤的 findings；
-- skill 表格：来源、token 成本、描述预览、文件路径；
-- 只写 `--html` 不带路径时默认 `./skills-report.html`；`--open` 自动打开浏览器。
-
-插件和 MCP 工具同样接受 `html` 参数，所以可以让 agent 先问你要存哪里——例如：*"把报告存到 D:\reports\skills.html"*。
+OpenCode 1.x 没有这条通知接口，同一段话交给模型，让它在回复里说出来。
 
 ### `plan`（到底能省多少 token？）
 
@@ -161,7 +155,7 @@ skills-doctor plan --json
 - **方案 B**：用最少的隐藏数量把总量压进预算（仍可 `@id` 加载；按单项节省从大到小取，对「最少隐藏数」是最优的）；
 - **推荐方案**：先精简再隐藏，不重复计算，并按 `--steps`（默认 100）折算总节省。
 
-超预算时 `check` 会打印一行提示，HTML 报告里有同样的「potential savings」卡片。
+超预算时 `check` 会打印一行提示。具体方案看 `plan`。
 
 ### `scan`
 
@@ -272,9 +266,8 @@ skills-doctor upgrade --apply    # npm install -g opencode-skills-doctor@latest
 
 它会注册：
 
-- `skills_doctor` 工具（命名空间 `skills`）—— agent 传 `{ directory?, budget?, html? }` 就能拿到 markdown 审计报告；
+- `skills_doctor` 工具（命名空间 `skills`）—— `{ directory?, budget? }` 返回对话简报，不写文件；
 - `/skills-doctor` 命令 —— 让 agent 跑一次审计并总结修复建议；
-- `/skills-report` —— 先问你要把 HTML 报告存到哪里，再写文件；
 - `/skills-upgrade` —— 检查 skills-doctor 自身有没有新版本。
 
 `@opencode/plugin` 是可选 peer 依赖，运行时由 OpenCode 提供。
@@ -316,7 +309,7 @@ npx opencode-skills-doctor install --client desktop
 ```
 
 - 在标准安装位置探测桌面版，并从 `resources/app.asar` 读出内置 core 版本（例如 1.17.11），据此选择对应插件 API；
-- 写入与 CLI 相同的插件条目和 `/skills-doctor`、`/skills-report`、`/skills-upgrade` 命令 —— 装完重启桌面应用；
+- 写入与 CLI 相同的插件条目和 `/skills-doctor`、`/skills-upgrade` 命令 —— 装完重启桌面应用；
 - `--client auto`（默认）在同时装了 CLI 时优先 CLI 版本；`--client opencode` 跳过桌面探测；
 - `uninstall --client desktop` 反向撤销。
 
@@ -331,16 +324,15 @@ npx opencode-skills-doctor install
 安装器会自动识别 OpenCode 版本并接好：
 
 - **2.x** —— 在 `opencode.json(c)` 里加 `"plugins": ["opencode-skills-doctor"]`；
-- **1.x** —— 把包装进 `~/.config/opencode`、写本地插件入口、生成 `/skills-doctor`、`/skills-report`、`/skills-upgrade` 三个 markdown 命令、补 `"type": "module"`；
+- **1.x** —— 把包装进 `~/.config/opencode`、写本地插件入口、生成 `/skills-doctor`、`/skills-upgrade` 两个 markdown 命令、补 `"type": "module"`；
 - 改配置前会备份为 `<config>.bak-<timestamp>`。
 
 支持 `--dry-run` 预览、`--config-dir <dir>` 指定配置目录、`--no-npm` 跳过装包。
 
 装好后你会得到：
 
-- `skills_doctor` 工具（可选 `html` 参数，把报告写到指定路径）；
+- `skills_doctor` 工具，返回对话简报，不写文件；
 - `/skills-doctor` 命令（1.x 是生成的 markdown 命令，2.x 是插件命令）；
-- `/skills-report` 命令（2.x）—— 会先问你要把 HTML 报告存到哪里；
 - `/skills-upgrade` 命令（2.x）—— 检查 skills-doctor 自身是否有新版本；
 - 当 skill 描述预算超标时，系统提示里会注入一次提醒（每个会话最多一次）。
 
@@ -395,7 +387,7 @@ npx -y opencode-skills-doctor install --client dsh
 
 它会找到 `~/.dsh/profiles/<profile>/cordis.patch.yml`（默认 `desktop`，否则用 `--profile <name>`），把 `mcp-skills-doctor` 这一行放在 `- insert:` 块里幂等写入，并把 `skills-doctor-audit` 技能复制到 `~/.dsh/skills/`。重启 DSH（启用 HMR 时会自动重载 patch）加载 MCP 工具；skill 目录有监听，无需重启。
 
-- 工具名 `mcp__skills_doctor__skills_doctor`，参数 `directory`、`budget`、`lang`、`global`、`html`；
+- 工具名 `mcp__skills_doctor__skills_doctor`，参数 `directory`、`budget`、`lang`、`global`；
 - `uninstall --client dsh` 同时移除配置条目和 skill；
 - `--dsh-home <dir>` 用于非默认的 DSH 主目录。
 
@@ -487,7 +479,7 @@ npx -y opencode-skills-doctor install --client kimi
 | `shadowed` | warn | 同一 ID 多处定义，只有一份生效，其余白占体积且容易改错 |
 | `flat-dir-collision` | warn | 同一来源同时存在 `<id>.md` 和 `<id>/SKILL.md` |
 | `duplicate-content` | warn | 不同 skill 正文完全相同 |
-| `near-duplicate-description` | warn | 两个 skill 的 description 相似度 ≥ 75%，模型容易选错 |
+| `near-duplicate-description` | warn | 去掉套话后，特征词重叠 ≥ 72%，或较短的触发词有 ≥ 85% 被另一条包含 |
 | `missing-description` | info | 没有 description，模型看不到它 |
 | `long-description` | warn | description > 240 字符（每个模型步骤都占上下文） |
 | `large-body` | warn | 正文 > 4000 tokens（调用时整段进上下文） |
@@ -560,7 +552,7 @@ npx -y opencode-skills-doctor install --client kimi
 **度量**
 
 - 默认 `budget`（1200 tokens）是建议值，不是硬限制；用 `.skills-doctor.json` 或 `--budget` 调整。
-- token 是启发式估算（CJK 约 1.7 字/token，其余约 4 字符/token），用于横向比较，不是精确计费。
+- token 按词估算（短英文词 1 token，每个汉字 1 token，更长的词每多 4 个字符加 1）。用来比较，不是精确计费。
 - `check` 不联网；要看 catalog 新版本用 `update --check-only`。
 - 配置优先级假设：全局配置 < 项目配置 < `skills` 数组顺序。
 

package/docs/REFERENCE.md

@@ -13,11 +13,11 @@ Local scanner, linter, fixer, updater and **OpenCode plugin** for agent skills
 | **Skill sources** | `.opencode/skills`, `.claude/skills`, `.agents/skills`, `.grok/skills`, `.cursor/skills`, `.hermes/skills`, `.kimi-code/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`) |
+| **Reports** | a chat notice in OpenCode, plus the terminal and JSON |
 | **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 |
+| **Quality** | 73 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
 
 ## Why
 
@@ -82,20 +82,13 @@ 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
+### Chat notice
 
-`--html [file]` writes a single self-contained HTML file (no external assets):
+OpenCode 2 posts one notice in the session the first time you send a message, when there is an error or a warning. The notice is a synthetic message with the description `skills-doctor`, so it shows as its own row. It does not start another model turn. `/skills-doctor` posts it again, including when nothing is wrong. The tool and the MCP server return the same short text and do not write a file. At most three findings are listed. Archive and hide still wait for you to confirm.
 
-- 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"*.
+On OpenCode 1.x the same text is handed to the model with an instruction to say it in the chat.
 
 ### `plan` (how many tokens can I actually save?)
 
@@ -112,7 +105,7 @@ It answers "how much can I cut, exactly?":
 - **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.
+`check` prints a one-line pointer when you are over budget. `plan` is the breakdown.
 
 ### `scan`
 
@@ -223,9 +216,8 @@ The package also exports an OpenCode 2.x plugin:
 
 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;
+- the `skills_doctor` tool (namespace `skills`) — `{ directory?, budget? }` returns the short chat briefing and writes nothing;
+- `/skills-doctor` — posts that briefing in the chat;
 - `/skills-upgrade` — checks whether skills-doctor itself has a newer version.
 
 `@opencode/plugin` is an optional peer dependency; OpenCode provides it at runtime.
@@ -267,7 +259,7 @@ 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;
+- writes the same plugin entry and `/skills-doctor` and `/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.
 
@@ -282,18 +274,17 @@ 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"`;
+- **1.x** — installs the package into `~/.config/opencode`, writes the local plugin entry, generates `/skills-doctor` 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.
+- the `skills_doctor` tool, which returns the chat briefing and writes nothing;
+- `/skills-doctor` (1.x: generated markdown command; 2.x: a notice posted in the chat);
+- `/skills-upgrade` (2.x) that checks for a newer skills-doctor;
+- one chat notice per session when a skill has an error or a warning. On 1.x the same text is given to the model to say out loud. `uninstall` deletes a leftover `/skills-report` command from older installs.
 
 ### Uninstall
 
@@ -346,7 +337,7 @@ 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`;
+- tool name `mcp__skills_doctor__skills_doctor`, arguments `directory`, `budget`, `lang`, `global`;
 - `uninstall --client dsh` removes both the patch entry and the skill;
 - `--dsh-home <dir>` for a non-standard DSH home.
 
@@ -438,7 +429,7 @@ It merges `skills-doctor` into `~/.kimi-code/mcp.json` (or `$KIMI_CODE_HOME/mcp.
 | `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 |
+| `near-duplicate-description` | warn | Distinctive words overlap by ≥ 72%, or a shorter trigger is ≥ 85% contained in a longer one. Shared boilerplate ("use this skill when…") is ignored |
 | `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) |
@@ -517,7 +508,7 @@ See [SECURITY.md](../SECURITY.md) for the full threat model, hardening checklist
 **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.
+- Token counts are a word-piece estimate (a short English word is 1 token, each CJK character is 1, longer words add 1 per 4 extra characters). 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.
 
@@ -552,7 +543,7 @@ Executing code is free, but the tool definition is part of the model's context.
 ## Development and contributing
 
 ```powershell
-npm test          # 58 tests (node test/doctor.test.mjs)
+npm test          # 73 tests (node test/doctor.test.mjs)
 npm run bench     # lint timing for 100/500/1000 skills
 ```
 

package/docs/assets/banner.svg

@@ -41,7 +41,7 @@
       <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>
+      <text x="22" y="192" fill="#8b9bb4">told you in the chat →</text>
     </g>
   </g>
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.9.4",
-  "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, Hermes Agent, Kimi Code and DeepSeek Harness.",
+  "version": "0.9.7",
+  "description": "Audit, fix and update agent skills: token cost, broken references, shadowed duplicates, catalog sync. Tells you in the chat. CLI, OpenCode plugin, MCP server; works with OpenCode, Claude Code, Codex, Grok CLI, Cursor, Hermes Agent, Kimi Code and DeepSeek Harness.",
   "type": "module",
   "exports": {
     ".": "./src/plugin.mjs",

package/skills/dsh-skills-doctor/SKILL.md

@@ -21,9 +21,9 @@ npx -y opencode-skills-doctor check --json
 Read `summary.advertisedTokens` (cost per model step), `summary.advertised` and `findings[]`.
 If the command fails, fall back to `opencode-skills-doctor` when installed globally, or ask the user to run it from the repo.
 
-## 2. Explain the top findings
+## 2. Tell the user in this chat
 
-Report at most three findings, in plain language, each with its token impact:
+Say at most three findings, in plain language. Do not write a report file.
 
 - `token-budget` — descriptions cost roughly N tokens on **every** model step;
 - `shadowed` — the same skill ID loads from several places, only one wins;
@@ -47,8 +47,3 @@ Report `recommended.savings` (per step), `recommended.final` and `recommended.st
 - Trim descriptions manually, keeping them discoverable
 - Ask first, then re-run `check` to confirm the new cost
 
-## 5. Optional shareable report
-
-```powershell
-npx -y opencode-skills-doctor check --html skills-report.html --open
-```

package/src/audit.mjs

@@ -67,6 +67,35 @@ export function auditSkills({
   }
 }
 
+/**
+ * 给对话用的短结论。agent 应原样告诉用户，不要再写成文件。
+ */
+export function formatChat(audit, { limit = 3 } = {}) {
+  const zh = audit.lang === "zh"
+  const problems = audit.findings.filter((finding) => finding.severity === "error" || finding.severity === "warn")
+  if (!problems.length) {
+    return zh
+      ? `skills-doctor：技能没有需要处理的问题。${audit.summary.advertised} 个会在每一步注入，大约 ${audit.summary.advertisedTokens} token。`
+      : `skills-doctor: no skill problems to act on. ${audit.summary.advertised} skills are injected on every step, about ${audit.summary.advertisedTokens} tokens.`
+  }
+  const lines = [
+    zh ? "skills-doctor：" : "skills-doctor:",
+    zh
+      ? `技能有 ${problems.length} 个问题：`
+      : `${problems.length} skill problem${problems.length === 1 ? "" : "s"}:`,
+  ]
+  for (const finding of problems.slice(0, limit)) lines.push(`- ${finding.message}`)
+  if (problems.length > limit) {
+    lines.push(zh ? `- 还有 ${problems.length - limit} 条，需要的话我再展开。` : `- ${problems.length - limit} more. Ask if you want them.`)
+  }
+  lines.push(
+    zh
+      ? "我不会改文件。你确认之后，我可以归档被盖住的副本，或把不常用的藏起来。"
+      : "I will not change any files. After you confirm, I can archive shadowed copies or hide skills you rarely use.",
+  )
+  return lines.join("\n")
+}
+
 /** 把审计结果渲染成适合给 agent / PR 评论用的 markdown。 */
 export function formatMarkdown(audit, { limit = 25 } = {}) {
   const lines = []

package/src/cli.mjs

@@ -11,7 +11,7 @@ import { startMcpServer } from "./mcp.mjs"
 import { installOpenCode, uninstallOpenCode } from "./install.mjs"
 import { installDsh, uninstallDsh } from "./dsh.mjs"
 import { installKimi, uninstallKimi } from "./kimi.mjs"
-import { writeHtmlReport, openReport } from "./html.mjs"
+
 import { planBudget } from "./plan.mjs"
 import {
   checkForUpdate,
@@ -80,7 +80,7 @@ function parseArgs(argv) {
     extraDirs: [],
     configDir: null,
     noNpm: false,
-    html: null,
+
     open: false,
     apply: false,
     updateCheck: true,
@@ -174,19 +174,6 @@ function parseArgs(argv) {
       case "--no-npm":
         options.noNpm = true
         break
-      case "--html": {
-        const next = args[i + 1]
-        if (next && !next.startsWith("-")) {
-          options.html = path.resolve(next)
-          i++
-        } else {
-          options.html = path.resolve("skills-report.html")
-        }
-        break
-      }
-      case "--open":
-        options.open = true
-        break
       case "--apply":
         options.apply = true
         break
@@ -838,23 +825,16 @@ export async function main(argv) {
     })
     const result = buildCheckResult(audit, options)
 
-    let htmlPath = null
-    if (options.html) {
-      htmlPath = writeHtmlReport(audit, options.html)
-      if (options.open) openReport(htmlPath)
-    }
-
     if (options.json) {
       console.log(
         JSON.stringify(
-          { ...result, html: htmlPath, skills: serializeSkills(audit.skills, audit.managed) },
+          { ...result, skills: serializeSkills(audit.skills, audit.managed) },
           null,
           2,
         ),
       )
     } else {
       printCheck(audit, result, options, t)
-      if (htmlPath) console.log(dim(t("check.htmlSaved", { path: htmlPath })))
       await maybeNotifyUpdate({ options, config: loaded.config, t })
     }
     process.exitCode = result.exitCode

package/src/discover.mjs

@@ -341,6 +341,7 @@ function buildSkill({ id, file, source, form }) {
   const description = typeof data.description === "string" ? data.description.trim() : ""
   const displayName = typeof data.name === "string" && data.name.trim() ? data.name.trim() : id
   const hidden = autoinvoke === false || disabled === true
+  const stepTokens = estimateTokens(`${id} ${displayName} ${description}`)
   let mtime = 0
   try {
     mtime = fs.statSync(file).mtimeMs
@@ -366,6 +367,7 @@ function buildSkill({ id, file, source, form }) {
     bodyTokens: estimateTokens(body),
     bytes,
     descriptionTokens: estimateTokens(description),
+    stepTokens,
     hash: sha1(body.replace(/\s+/g, " ").trim()),
     mtime,
   }