opencode-skills-doctor 0.5.1 → 0.5.2

package/README.md

@@ -354,10 +354,20 @@ DSH ships an MCP client bundle (`@deepseek-ai/dsh-mcp-client`). Add one entry to
     args: ["-y", "opencode-skills-doctor", "mcp"]
 ```
 
-Restart DSH. The tool shows up as `mcp__skills_doctor__skills_doctor`.
+Restart DSH. The tool shows up as `mcp__skills_doctor__skills_doctor` and accepts `directory`, `budget`, `lang`, `global` and `html`.
 
 On Windows, if the stdio spawn cannot resolve `npx`, use `command: cmd` and `args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`.
 
+#### Optional skill (tells the model when to audit)
+
+The repo ships a DSH skill at `skills/dsh-skills-doctor/`:
+
+```powershell
+Copy-Item -Recurse skills\dsh-skills-doctor "$env:USERPROFILE\.dsh\skills\"
+```
+
+DSH watches skill roots, so `skills-doctor-audit` appears in the catalog without a restart. The skill runs `check`/`plan`, explains the token impact, and only proposes fixes — it never edits skills without confirmation.
+
 ## How it works
 
 **Audit pipeline**

package/docs/README.zh-CN.md

@@ -354,10 +354,20 @@ DSH 自带 MCP 客户端 bundle（`@deepseek-ai/dsh-mcp-client`）。在 profile
     args: ["-y", "opencode-skills-doctor", "mcp"]
 ```
 
-重启 DSH。工具会以 `mcp__skills_doctor__skills_doctor` 出现。
+重启 DSH。工具会以 `mcp__skills_doctor__skills_doctor` 出现，参数支持 `directory`、`budget`、`lang`、`global`、`html`。
 
 Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c", "npx", "-y", "opencode-skills-doctor", "mcp"]`。
 
+#### 可选技能包（告诉模型什么时候该体检）
+
+仓库自带一个 DSH skill：`skills/dsh-skills-doctor/`：
+
+```powershell
+Copy-Item -Recurse skills\dsh-skills-doctor "$env:USERPROFILE\.dsh\skills\"
+```
+
+DSH 会监听 skill 目录，`skills-doctor-audit` 无需重启就会出现在目录里。它会跑 `check`/`plan`、解释 token 影响，并且只提出修复建议 —— 不经确认不会改 skill 文件。
+
 ## 工作原理
 
 **审计流程**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.5.1",
+  "version": "0.5.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 and Cursor skill layouts.",
   "type": "module",
   "exports": {
@@ -37,6 +37,7 @@
     "bin",
     "src",
     "docs",
+    "skills",
     "README.md",
     "SECURITY.md",
     "SECURITY.zh-CN.md"

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

@@ -0,0 +1,54 @@
+---
+name: skills-doctor-audit
+description: Audit installed agent skills for per-step token cost, shadowed duplicates, broken references and budget overruns, then propose concrete fixes.
+whenToUse: Use when the user mentions too many skills, context bloat, token cost, duplicate or missing skills, or asks for a skill health check.
+metadata:
+  author: wangyuchen5110
+  source: opencode-skills-doctor
+---
+
+# Skill audit workflow
+
+Audit the user's installed skills and turn the result into a short, actionable answer.
+Never modify skill files without explicit confirmation.
+
+## 1. Run the read-only audit
+
+```powershell
+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
+
+Report at most three findings, in plain language, each with its token impact:
+
+- `token-budget` — descriptions cost roughly N tokens on **every** model step;
+- `shadowed` — the same skill ID loads from several places, only one wins;
+- `long-description` / `large-body` — descriptions or bodies that are paid on every step / every invocation;
+- `broken-reference` — a `references/` or `scripts/` file the skill points at is missing.
+
+## 3. Show what can actually be saved
+
+```powershell
+npx -y opencode-skills-doctor plan --json
+```
+
+Report `recommended.savings` (per step), `recommended.final` and `recommended.stepsSavings`
+(per 100 steps). Explain the difference: trimming descriptions keeps discoverability; hiding a skill
+(`autoinvoke: false`) removes it from the advertised list but keeps `@id` loading.
+
+## 4. Propose fixes — do not apply silently
+
+- Hide low-frequency skills: `npx -y opencode-skills-doctor fix --hide id1,id2`
+- Archive shadowed duplicates (reversible): `npx -y opencode-skills-doctor fix`
+- 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
+```