opencode-skills-doctor 0.3.14 → 0.4.0

package/README.md

@@ -15,13 +15,14 @@ Local scanner, linter, fixer, updater and **OpenCode plugin** for agent skills
 | | |
 |---|---|
 | **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 |
+| **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`) |
 | **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 |
+| **Quality** | 49 tests, CI on ubuntu/macos/windows × Node 20/22/24 |
 
 ## Why
 
@@ -86,8 +87,21 @@ 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"*.
+
 ### `scan`
 
 Lists every skill with its source, precedence, whether the model can see it, and token cost.
@@ -221,8 +235,9 @@ Use `--dry-run` to preview, `--config-dir <dir>` for a custom config location, a
 
 Once installed you get:
 
-- the `skills_doctor` tool;
+- 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;
 - a one-time system-prompt warning when the skill description budget is exceeded.
 
 ### Uninstall
@@ -305,6 +320,17 @@ On Windows, if the stdio spawn cannot resolve `npx`, use `command: cmd` and `arg
 
 `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 |
@@ -321,6 +347,10 @@ On Windows, if the stdio spawn cannot resolve `npx`, use `command: cmd` and `arg
 | `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 |
@@ -340,9 +370,13 @@ On Windows, if the stdio spawn cannot resolve `npx`, use `command: cmd` and `arg
 2. project `.claude/skills` (from the project root up to the current directory)
 3. `~/.agents/skills`
 4. project `.agents/skills`
-5. `~/.config/opencode/skills`
-6. project `.opencode/skills`
-7. 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
+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
 

package/docs/README.zh-CN.md

@@ -15,13 +15,14 @@ OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **Open
 | | |
 |---|---|
 | **是什么** | 审计、修复、更新 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 |
+| **形态** | CLI · OpenCode 插件（1.x / 2.x）· MCP server（Claude Code、Codex、DSH…）· 兼容 Grok CLI |
+| **来源** | `.opencode/skills`、`.claude/skills`、`.agents/skills`、`.grok/skills`、`.cursor/skills`、`opencode.json(c)` 配置、HTTP catalog |
+| **能查** | 同 ID 遮蔽、重复、超长描述、超大正文、每步 token 预算、断链引用、非法 frontmatter、空正文、陈旧 skill |
 | **能修** | 归档遮蔽定义（可逆）、隐藏低频 skill、catalog 同步并检测 drift |
+| **报告** | 终端、JSON，或自包含 HTML（`--html [file] --open`） |
 | **成本** | CLI 0 token；插件工具定义约 191/步，另有每会话一次预警 |
 | **要求** | Node ≥ 20，零运行时依赖 |
-| **质量** | 41 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
+| **质量** | 49 个测试，ubuntu/macos/windows × Node 20/22/24 CI |
 
 ## 为什么需要它
 
@@ -86,8 +87,21 @@ 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 文件（无外部资源）：
+
+- 摘要卡片 + 上下文预算条；
+- 可按严重级别和文本过滤的 findings；
+- skill 表格：来源、token 成本、描述预览、文件路径；
+- 只写 `--html` 不带路径时默认 `./skills-report.html`；`--open` 自动打开浏览器。
+
+插件和 MCP 工具同样接受 `html` 参数，所以可以让 agent 先问你要存哪里——例如：*"把报告存到 D:\reports\skills.html"*。
+
 ### `scan`
 
 列出所有 skill 及其来源、优先级、是否会被模型看到、token 占用。
@@ -221,8 +235,9 @@ npx opencode-skills-doctor install
 
 装好后你会得到：
 
-- `skills_doctor` 工具；
+- `skills_doctor` 工具（可选 `html` 参数，把报告写到指定路径）；
 - `/skills-doctor` 命令（1.x 是生成的 markdown 命令，2.x 是插件命令）；
+- `/skills-report` 命令（2.x）—— 会先问你要把 HTML 报告存到哪里；
 - 当 skill 描述预算超标时，系统提示里会注入一次提醒（每个会话最多一次）。
 
 ### 卸载
@@ -305,6 +320,17 @@ Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c",
 
 `check` 会读 lockfile，报告 drift（`managed-drift`）、文件缺失（`managed-missing`）和未知 lock 版本（`lock-version-unsupported`）；再跑一次 `update` 会重下被改坏的文件。
 
+### Grok CLI
+
+Grok 从 `.grok/skills`（项目、仓库、`~/.grok/skills`）以及 `.claude/skills`、`.cursor/skills`、`.agents/skills` 发现 skill。skills-doctor 扫描的正是同一批位置：
+
+```powershell
+skills-doctor check --root .        # 覆盖当前项目的 Grok skill
+skills-doctor check --root $HOME    # 覆盖 ~/.grok/skills 等用户级 skill
+```
+
+不需要额外安装——Grok 原生加载 `SKILL.md`。如果该 Grok 版本支持 MCP，还可以把上面的 MCP server 接进去，让模型自己调用 `skills_doctor`。
+
 ## 检测规则
 
 | 规则 | 级别 | 含义 |
@@ -321,6 +347,10 @@ Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c",
 | `invalid-id` | info | 不符合 kebab-case 规范 |
 | `hidden-skill` | info | 被 `opencode/autoinvoke: false` 或 `disable-model-invocation: true` 隐藏 |
 | `stale-skill` | info | `--stale-days` 指定的天数内没更新 |
+| `broken-reference` | warn | 引用的 `references/`、`scripts/`、`assets/`、`templates/`、`examples/` 文件不存在 |
+| `reference-outside-skill` | info | 被引用的文件在 skill 目录之外（影响可移植性） |
+| `invalid-frontmatter` | warn | `---` 未闭合，或 name/description 非字符串 / metadata 非对象 |
+| `empty-body` | info | 正文几乎是空的，skill 没有实际指令 |
 | `managed-drift` | warn | 由 update 安装的文件在更新后被改过 |
 | `managed-missing` | warn | lock 里记录了，但本地文件没了 |
 | `managed-unsafe` | warn | lock 里有路径穿越等不安全路径 |
@@ -340,9 +370,13 @@ Windows 上如果 stdio 起不来 `npx`，改成 `command: cmd`、`args: ["/c",
 2. 项目 `.claude/skills`（项目根 → 当前目录逐级）
 3. `~/.agents/skills`
 4. 项目 `.agents/skills`
-5. `~/.config/opencode/skills`
-6. 项目 `.opencode/skills`
-7. `opencode.json(c)` 的 `skills` 数组（2.x）或 `skills.paths`（1.x）；相对路径按当前工作目录解析，支持 `~/`、绝对路径、HTTP catalog
+5. `~/.cursor/skills`
+6. 项目 `.cursor/skills`
+7. `~/.grok/skills`
+8. 项目 `.grok/skills`
+9. `~/.config/opencode/skills`
+10. 项目 `.opencode/skills`
+11. `opencode.json(c)` 的 `skills` 数组（2.x）或 `skills.paths`（1.x）；相对路径按当前工作目录解析，支持 `~/`、绝对路径、HTTP catalog
 
 ## JSON 输出
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.3.14",
-  "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).",
+  "version": "0.4.0",
+  "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": {
     ".": "./src/plugin.mjs",

package/src/cli.mjs

@@ -9,6 +9,7 @@ import { auditSkills } from "./audit.mjs"
 import { loadConfig } from "./config.mjs"
 import { startMcpServer } from "./mcp.mjs"
 import { installOpenCode, uninstallOpenCode } from "./install.mjs"
+import { writeHtmlReport, openReport } from "./html.mjs"
 import { padDisplay } from "./parse.mjs"
 import { detectLang, normalizeLang, translator } from "./i18n.mjs"
 
@@ -38,6 +39,10 @@ const HINT_KEYS = {
   "invalid-id": "hint.invalid-id",
   "hidden-skill": "hint.hidden-skill",
   "stale-skill": "hint.stale-skill",
+  "invalid-frontmatter": "hint.invalid-frontmatter",
+  "empty-body": "hint.empty-body",
+  "broken-reference": "hint.broken-reference",
+  "reference-outside-skill": "hint.reference-outside-skill",
 }
 
 function parseArgs(argv) {
@@ -59,6 +64,8 @@ function parseArgs(argv) {
     prune: false,
     configDir: null,
     noNpm: false,
+    html: null,
+    open: false,
     help: false,
     version: false,
   }
@@ -125,6 +132,19 @@ 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 "-h":
       case "--help":
         options.help = true
@@ -506,21 +526,27 @@ export async function main(argv) {
       budget: options.budget,
       staleDays: options.staleDays,
     })
+    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(
-          { ...buildCheckResult(audit, options), skills: serializeSkills(audit.skills, audit.managed) },
+          { ...result, html: htmlPath, skills: serializeSkills(audit.skills, audit.managed) },
           null,
           2,
         ),
       )
     } else {
-      const result = buildCheckResult(audit, options)
       printCheck(audit, result, options, t)
-      process.exitCode = result.exitCode
-      return
+      if (htmlPath) console.log(dim(t("check.htmlSaved", { path: htmlPath })))
     }
-    process.exitCode = buildCheckResult(audit, options).exitCode
+    process.exitCode = result.exitCode
     return
   }
 

package/src/discover.mjs

@@ -110,14 +110,19 @@ function isUnder(parent, child) {
 }
 
 /**
- * 按官方文档的注册顺序返回 skill 来源（顺序即优先级，越后越高）：
+ * 返回 skill 来源（顺序即优先级，越后越高）。这是多个 agent 的并集，
+ * 不同 agent 的真实优先级可能不同（Grok 的 local 最高，OpenCode 的 config 最高）：
  *  1. ~/.claude/skills
  *  2. 项目 .claude/skills（远端 → cwd）
  *  3. ~/.agents/skills
  *  4. 项目 .agents/skills（远端 → cwd）
- *  5. ~/.config/opencode/skills
- *  6. 项目 .opencode/skills（项目根 → cwd）
- *  7. opencode.json(c) 里的 skills 数组
+ *  5. ~/.cursor/skills
+ *  6. 项目 .cursor/skills
+ *  7. ~/.grok/skills
+ *  8. 项目 .grok/skills
+ *  9. ~/.config/opencode/skills
+ * 10. 项目 .opencode/skills（项目根 → cwd）
+ * 11. opencode.json(c) 里的 skills 数组 / skills.paths
  */
 export function discoverSources({ cwd = process.cwd(), home = os.homedir(), includeGlobal = true } = {}) {
   const projectRoot = findProjectRoot(cwd) ?? path.resolve(cwd)
@@ -140,6 +145,12 @@ export function discoverSources({ cwd = process.cwd(), home = os.homedir(), incl
   if (includeGlobal) addSource("agents-global", "global", path.join(home, ".agents", "skills"))
   for (const dir of projectChain) addSource("agents-project", "project", path.join(dir, ".agents", "skills"))
 
+  if (includeGlobal) addSource("cursor-global", "global", path.join(home, ".cursor", "skills"))
+  for (const dir of projectChain) addSource("cursor-project", "project", path.join(dir, ".cursor", "skills"))
+
+  if (includeGlobal) addSource("grok-global", "global", path.join(home, ".grok", "skills"))
+  for (const dir of projectChain) addSource("grok-project", "project", path.join(dir, ".grok", "skills"))
+
   if (includeGlobal) addSource("opencode-global", "global", path.join(home, ".config", "opencode", "skills"))
   for (const dir of projectChain) addSource("opencode-project", "project", path.join(dir, ".opencode", "skills"))
 
@@ -246,7 +257,14 @@ function buildSkill({ id, file, source, form }) {
   } catch {
     text = ""
   }
-  const { data, body } = parseFrontmatter(text)
+  const { data, body, hasFrontmatter } = parseFrontmatter(text)
+  const startsWithFence = /^---\r?\n/.test(text)
+  const frontmatterBroken = startsWithFence && !hasFrontmatter
+  const frontmatterInvalid =
+    hasFrontmatter &&
+    ((data.name !== undefined && typeof data.name !== "string") ||
+      (data.description !== undefined && typeof data.description !== "string") ||
+      (data.metadata !== undefined && (typeof data.metadata !== "object" || data.metadata === null)))
   const autoinvoke = data?.metadata?.["opencode/autoinvoke"]
   const disabled = data?.["disable-model-invocation"]
   const description = typeof data.description === "string" ? data.description.trim() : ""
@@ -269,7 +287,11 @@ function buildSkill({ id, file, source, form }) {
     disabled,
     hidden,
     advertised: Boolean(description) && !hidden,
+    hasFrontmatter,
+    frontmatterBroken,
+    frontmatterInvalid,
     body,
+    bodyChars: body.trim().length,
     bodyTokens: estimateTokens(body),
     bytes: Buffer.byteLength(text),
     descriptionTokens: estimateTokens(description),

package/src/html.mjs

@@ -0,0 +1,167 @@
+import fs from "node:fs"
+import path from "node:path"
+import { spawn } from "node:child_process"
+
+function esc(value) {
+  return String(value ?? "").replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char])
+}
+
+const SEVERITY_LABEL = { error: "error", warn: "warn", info: "info" }
+
+/** 生成自包含 HTML 报告（无外部资源，可直接分享/作 CI artifact）。 */
+export function renderHtml(audit, { title = "skills-doctor report", now = new Date() } = {}) {
+  const summary = audit.summary
+  const counts = audit.counts
+  const budget = audit.budget
+  const ratio = budget > 0 ? Math.min(1.5, summary.advertisedTokens / (budget * 2)) : 0
+  const barWidth = Math.min(100, Math.round(ratio * 100))
+  const barClass = summary.advertisedTokens > budget * 2 ? "over" : summary.advertisedTokens > budget ? "warn" : "ok"
+
+  const findings = audit.findings
+    .map(
+      (finding) => `<tr class="finding ${finding.severity}" data-severity="${finding.severity}">
+  <td><span class="badge ${finding.severity}">${SEVERITY_LABEL[finding.severity] ?? finding.severity}</span></td>
+  <td class="rule">${esc(finding.rule)}</td>
+  <td>${esc(finding.message)}</td>
+</tr>`,
+    )
+    .join("\n")
+
+  const skills = audit.skills
+    .map(
+      (skill) => `<tr class="skill">
+  <td class="mono">${esc(skill.id)}</td>
+  <td>${esc(skill.source.scope)}</td>
+  <td>${skill.advertised ? "yes" : "no"}</td>
+  <td class="num">${skill.descriptionTokens}</td>
+  <td class="num">${skill.bodyTokens}</td>
+  <td class="desc">${esc(String(skill.description ?? "").slice(0, 80))}</td>
+  <td class="mono path">${esc(skill.file)}</td>
+</tr>`,
+    )
+    .join("\n")
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<style>
+  :root { color-scheme: light dark; --fg:#1f2328; --muted:#656d76; --bg:#fff; --card:#f6f8fa; --border:#d0d7de; --red:#cf222e; --yellow:#9a6700; --green:#1a7f37; --blue:#0969da; }
+  @media (prefers-color-scheme: dark) { :root { --fg:#e6edf3; --muted:#8d96a0; --bg:#0d1117; --card:#161b22; --border:#30363d; --red:#ff7b72; --yellow:#d29922; --green:#3fb950; --blue:#58a6ff; } }
+  * { box-sizing: border-box; }
+  body { margin:0; padding:32px; font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif; color:var(--fg); background:var(--bg); }
+  h1 { margin:0 0 4px; font-size:24px; }
+  h2 { margin:32px 0 12px; font-size:18px; }
+  .sub { color:var(--muted); font-size:12px; }
+  .cards { display:grid; grid-template-columns:repeat(auto-fit,minmax(150px,1fr)); gap:12px; margin:20px 0; }
+  .card { background:var(--card); border:1px solid var(--border); border-radius:10px; padding:12px 14px; }
+  .card .k { color:var(--muted); font-size:12px; }
+  .card .v { font-size:22px; font-weight:600; margin-top:2px; }
+  .card.error .v { color:var(--red); } .card.warn .v { color:var(--yellow); } .card.info .v { color:var(--blue); }
+  .bar { height:10px; border-radius:6px; background:var(--card); border:1px solid var(--border); overflow:hidden; margin:8px 0 4px; }
+  .bar > span { display:block; height:100%; width:${barWidth}%; }
+  .bar > span.ok { background:var(--green); } .bar > span.warn { background:var(--yellow); } .bar > span.over { background:var(--red); }
+  table { width:100%; border-collapse:collapse; background:var(--bg); border:1px solid var(--border); border-radius:10px; overflow:hidden; }
+  th, td { text-align:left; padding:8px 10px; border-bottom:1px solid var(--border); vertical-align:top; }
+  th { background:var(--card); font-size:12px; color:var(--muted); text-transform:uppercase; letter-spacing:.03em; }
+  tr:last-child td { border-bottom:none; }
+  .badge { display:inline-block; padding:1px 8px; border-radius:999px; font-size:11px; font-weight:600; border:1px solid currentColor; }
+  .badge.error { color:var(--red); } .badge.warn { color:var(--yellow); } .badge.info { color:var(--blue); }
+  .rule { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; white-space:nowrap; }
+  .mono { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; }
+  .path { color:var(--muted); word-break:break-all; }
+  .num { text-align:right; font-variant-numeric:tabular-nums; }
+  .toolbar { display:flex; gap:8px; flex-wrap:wrap; margin:12px 0; }
+  .toolbar button, .toolbar input { font:inherit; padding:6px 10px; border-radius:8px; border:1px solid var(--border); background:var(--card); color:var(--fg); }
+  .toolbar button.active { border-color:var(--blue); color:var(--blue); }
+  .empty { color:var(--muted); padding:16px; }
+  footer { margin-top:40px; color:var(--muted); font-size:12px; }
+</style>
+</head>
+<body>
+  <h1>${esc(title)}</h1>
+  <div class="sub">generated ${esc(now.toISOString())} · ${esc(audit.cwd)}</div>
+
+  <div class="cards">
+    <div class="card"><div class="k">definitions</div><div class="v">${summary.total}</div></div>
+    <div class="card"><div class="k">unique IDs</div><div class="v">${summary.unique}</div></div>
+    <div class="card"><div class="k">advertised</div><div class="v">${summary.advertised}</div></div>
+    <div class="card"><div class="k">description tokens / step</div><div class="v">${summary.advertisedTokens}</div></div>
+    <div class="card error"><div class="k">errors</div><div class="v">${counts.errors}</div></div>
+    <div class="card warn"><div class="k">warnings</div><div class="v">${counts.warnings}</div></div>
+    <div class="card info"><div class="k">info</div><div class="v">${counts.infos}</div></div>
+  </div>
+
+  <h2>Context budget</h2>
+  <div class="bar"><span class="${barClass}"></span></div>
+  <div class="sub">${summary.advertisedTokens} tokens vs budget ${budget}${summary.advertisedTokens > budget * 2 ? " (over 2x)" : summary.advertisedTokens > budget ? " (over)" : " (ok)"}</div>
+
+  <h2>Findings (${audit.findings.length})</h2>
+  <div class="toolbar">
+    <button data-filter="all" class="active">all</button>
+    <button data-filter="error">error</button>
+    <button data-filter="warn">warn</button>
+    <button data-filter="info">info</button>
+    <input id="q" placeholder="filter text…" />
+  </div>
+  <table id="findings">
+    <thead><tr><th>severity</th><th>rule</th><th>message</th></tr></thead>
+    <tbody>
+${findings || '<tr><td colspan="3" class="empty">No problems found.</td></tr>'}
+    </tbody>
+  </table>
+
+  <h2>Skills (${audit.skills.length})</h2>
+  <table>
+    <thead><tr><th>ID</th><th>scope</th><th>advertised</th><th>desc tokens</th><th>body tokens</th><th>description</th><th>file</th></tr></thead>
+    <tbody>
+${skills}
+    </tbody>
+  </table>
+
+  <footer>skills-doctor · ${esc(audit.version ?? "")} · updates: re-run <code>skills-doctor check --html</code></footer>
+
+<script>
+  const buttons = [...document.querySelectorAll("[data-filter]")]
+  const q = document.getElementById("q")
+  let active = "all"
+  function apply() {
+    const text = (q.value || "").toLowerCase()
+    for (const row of document.querySelectorAll("tr.finding")) {
+      const okSeverity = active === "all" || row.dataset.severity === active
+      const okText = !text || row.textContent.toLowerCase().includes(text)
+      row.style.display = okSeverity && okText ? "" : "none"
+    }
+  }
+  for (const button of buttons) {
+    button.addEventListener("click", () => {
+      active = button.dataset.filter
+      for (const other of buttons) other.classList.toggle("active", other === button)
+      apply()
+    })
+  }
+  q.addEventListener("input", apply)
+</script>
+</body>
+</html>
+`
+}
+
+export function writeHtmlReport(audit, file, options = {}) {
+  const target = path.resolve(file)
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(target, renderHtml(audit, options), "utf8")
+  return target
+}
+
+/** 用系统默认程序打开报告；失败时静默（调用方已经知道路径）。 */
+export function openReport(file) {
+  const target = path.resolve(file)
+  try {
+    if (process.platform === "win32") spawn("cmd", ["/c", "start", "", target], { detached: true, stdio: "ignore" }).unref()
+    else if (process.platform === "darwin") spawn("open", [target], { detached: true, stdio: "ignore" }).unref()
+    else spawn("xdg-open", [target], { detached: true, stdio: "ignore" }).unref()
+  } catch {}
+}

package/src/i18n.mjs

@@ -29,6 +29,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
+  --html [file]        check: write a self-contained HTML report (default: skills-report.html)
+  --open               check: open the HTML report after writing it
   --config-dir <dir>   install/uninstall: OpenCode config directory (default: ~/.config/opencode)
   --no-npm             install/uninstall: do not run npm (1.x)
   -h, --help           show this help
@@ -47,6 +49,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "check.configError": "  ! cannot parse config: {path} ({error})",
     "check.missingPath": "  ! path in config does not exist: {path}",
     "check.none": "No problems found.",
+    "check.htmlSaved": "  HTML report: {path}",
     "check.summary": "{errors} error, {warnings} warn, {infos} info",
     "check.strict": " (--strict: warnings also fail)",
     "check.hints": "Hints:",
@@ -121,6 +124,10 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "hint.invalid-id": "Use lowercase kebab-case and keep it aligned with the directory name.",
     "hint.hidden-skill": "Confirm the skill is intentionally hidden; hidden skills are not advertised.",
     "hint.stale-skill": "Confirm the content is still current, or delete it.",
+    "hint.invalid-frontmatter": "Fix the YAML frontmatter: closing ---, string name/description, object metadata.",
+    "hint.empty-body": "Add real instructions to the body, or delete the skill.",
+    "hint.broken-reference": "Fix the path or remove the reference; missing files silently break the skill.",
+    "hint.reference-outside-skill": "Keep referenced files inside the skill directory so the skill stays portable.",
 
     "lint.shadowed":
       'ID "{id}" is defined {count} times; the effective definition is {winner}; the other {losers} are shadowed (dead weight, easy to edit the wrong file)',
@@ -140,6 +147,12 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "lint.tokenBudgetError":
       "Advertised skill descriptions cost about {tokens} tokens per model step, over 2x the {budget} budget",
     "lint.tooManySkills": "{count} skills are advertised to the model (recommended ≤ 60)",
+    "lint.invalidFrontmatter": '"{id}" has malformed frontmatter: {detail}',
+    "lint.frontmatterUnclosed": "missing closing ---",
+    "lint.frontmatterTypes": "name/description/metadata have wrong types",
+    "lint.emptyBody": '"{id}" body is nearly empty ({chars} chars)',
+    "lint.brokenReference": '"{id}" references missing files: {refs}',
+    "lint.referenceOutside": '"{id}" references files outside its skill directory: {refs}',
 
     "managed.lockUnsupported":
       "Lock version {version} is newer than the supported {supported}; parsing in compatibility mode (unknown fields ignored)",
@@ -188,6 +201,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
+  --html [file]       check: 生成自包含 HTML 报告（默认 skills-report.html）
+  --open              check: 写完报告后用浏览器打开
   --config-dir <dir>  install/uninstall: OpenCode 配置目录（默认 ~/.config/opencode）
   --no-npm            install/uninstall: 不执行 npm（1.x）
   -h, --help          帮助
@@ -206,6 +221,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "check.configError": "  ! 配置文件无法解析: {path}（{error}）",
     "check.missingPath": "  ! 配置里引用的路径不存在: {path}",
     "check.none": "没有发现问题。",
+    "check.htmlSaved": "  HTML 报告: {path}",
     "check.summary": "{errors} error, {warnings} warn, {infos} info",
     "check.strict": "（--strict：warning 也会非 0 退出）",
     "check.hints": "建议:",
@@ -278,6 +294,10 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "hint.invalid-id": "改成小写 kebab-case，并与目录名对齐。",
     "hint.hidden-skill": "确认是刻意隐藏；隐藏的 skill 不会出现在模型列表里。",
     "hint.stale-skill": "确认内容没过期，或删掉。",
+    "hint.invalid-frontmatter": "修好 frontmatter：闭合的 ---、字符串形式的 name/description、对象形式的 metadata。",
+    "hint.empty-body": "给正文补上真正的说明，否则删掉这个 skill。",
+    "hint.broken-reference": "修正路径或删掉引用；缺失的文件会让 skill 静默失效。",
+    "hint.reference-outside-skill": "把被引用的文件放进 skill 目录，保证 skill 可移植。",
 
     "lint.shadowed":
       'ID "{id}" 有 {count} 处定义，实际生效的是 {winner}；其余 {losers} 处被遮蔽（白占体积、容易改错文件）',
@@ -293,6 +313,12 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "lint.tokenBudget": "模型每步要看到的 skill 描述约 {tokens} tokens，超过预算 {budget}",
     "lint.tokenBudgetError": "模型每步要看到的 skill 描述约 {tokens} tokens，超过预算 {budget} 的 2 倍",
     "lint.tooManySkills": "有 {count} 个 skill 会展示给模型（建议 ≤ 60）",
+    "lint.invalidFrontmatter": '"{id}" 的 frontmatter 格式有问题：{detail}',
+    "lint.frontmatterUnclosed": "缺少闭合的 ---",
+    "lint.frontmatterTypes": "name/description/metadata 类型不对",
+    "lint.emptyBody": '"{id}" 正文几乎是空的（{chars} 字符）',
+    "lint.brokenReference": '"{id}" 引用了不存在的文件：{refs}',
+    "lint.referenceOutside": '"{id}" 引用了 skill 目录之外的文件：{refs}',
 
     "managed.lockUnsupported":
       "lock 版本 {version} 高于本工具支持的 {supported}，已按兼容模式解析（未知字段忽略）",

package/src/install.mjs

@@ -6,7 +6,6 @@ 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`
 
@@ -16,6 +15,17 @@ 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
 `
 
+const V1_REPORT_COMMAND = `---
+description: Write an HTML skills report to a path you choose
+---
+Ask the user where to save the HTML report (default ./skills-report.html), then call the skills_doctor tool with the html argument set to that path and tell them where it was written. $ARGUMENTS
+`
+
+const V1_COMMANDS = [
+  { file: "skills-doctor.md", body: V1_COMMAND },
+  { file: "skills-report.md", body: V1_REPORT_COMMAND },
+]
+
 export function defaultConfigDir() {
   const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config")
   return path.join(base, "opencode")
@@ -139,7 +149,6 @@ export function installOpenCode({ configDir = defaultConfigDir(), version = null
 
   // 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"))
@@ -167,14 +176,17 @@ export function installOpenCode({ configDir = defaultConfigDir(), version = null
     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}`)
+  for (const command of V1_COMMANDS) {
+    const commandFile = path.join(dir, "command", command.file)
+    if (!fs.existsSync(commandFile)) {
+      if (!dryRun) {
+        fs.mkdirSync(path.dirname(commandFile), { recursive: true })
+        fs.writeFileSync(commandFile, command.body, "utf8")
+        act(`wrote command ${commandFile}`)
+      } else dry(`write command ${commandFile}`)
+    } else {
+      act(`command already exists ${commandFile}`)
+    }
   }
 
   const nextPlugin = ensureUniqueEntry(config.plugin, pluginPath)
@@ -265,7 +277,6 @@ export function uninstallOpenCode({ configDir = defaultConfigDir(), version = nu
   }
 
   const pluginFile = path.join(dir, "plugins", PLUGIN_FILE)
-  const commandFile = path.join(dir, "command", COMMAND_FILE)
 
   if (Array.isArray(config.plugin) && config.plugin.includes(pluginFile)) {
     const next = config.plugin.filter((entry) => entry !== pluginFile)
@@ -281,7 +292,10 @@ export function uninstallOpenCode({ configDir = defaultConfigDir(), version = nu
 
   if (fs.existsSync(pluginFile)) {
     const content = readText(pluginFile) ?? ""
-    if (content.includes("Generated by skills-doctor install")) {
+    const generated =
+      content.includes("Generated by skills-doctor install") ||
+      (content.includes("SkillsDoctorPlugin") && content.includes("opencode-skills-doctor/v1"))
+    if (generated) {
       if (!dryRun) {
         fs.rmSync(pluginFile, { force: true })
         act(`deleted ${pluginFile}`)
@@ -291,7 +305,9 @@ export function uninstallOpenCode({ configDir = defaultConfigDir(), version = nu
     }
   }
 
-  if (fs.existsSync(commandFile)) {
+  for (const command of V1_COMMANDS) {
+    const commandFile = path.join(dir, "command", command.file)
+    if (!fs.existsSync(commandFile)) continue
     const content = readText(commandFile) ?? ""
     if (content.includes("skills_doctor tool")) {
       if (!dryRun) {

package/src/lint.mjs

@@ -1,4 +1,7 @@
+import fs from "node:fs"
+import path from "node:path"
 import { estimateTokens } from "./parse.mjs"
+import { extractReferences } from "./refs.mjs"
 import { translator } from "./i18n.mjs"
 
 export const SEVERITY_ORDER = { error: 0, warn: 1, info: 2 }
@@ -117,6 +120,49 @@ export function lint(skills, options = {}) {
       add("invalid-id", "info", t("lint.invalidId", { id: skill.id }), { skills: [skill.id] })
     }
 
+    if (skill.frontmatterBroken) {
+      add("invalid-frontmatter", "warn", t("lint.invalidFrontmatter", { id: skill.id, detail: t("lint.frontmatterUnclosed") }), {
+        skills: [skill.id],
+      })
+    } else if (skill.frontmatterInvalid) {
+      add("invalid-frontmatter", "warn", t("lint.invalidFrontmatter", { id: skill.id, detail: t("lint.frontmatterTypes") }), {
+        skills: [skill.id],
+      })
+    }
+
+    if (skill.bodyChars < 20) {
+      add("empty-body", "info", t("lint.emptyBody", { id: skill.id, chars: skill.bodyChars }), { skills: [skill.id] })
+    }
+
+    // 只审计「skill 本地资源目录」的引用，避免把 npm 包名、项目相对路径误报成断链
+    const refs = extractReferences(skill.body).filter((ref) => {
+      if (ref.startsWith("@") || ref.endsWith("/")) return false
+      return /^(?:\.\/)?(?:references|scripts|assets|templates|examples)\//.test(ref)
+    })
+    if (refs.length) {
+      const base = path.resolve(path.dirname(skill.file))
+      const missingRefs = []
+      const outsideRefs = []
+      for (const ref of refs) {
+        const target = path.resolve(base, ref)
+        if (target !== base && !target.startsWith(base + path.sep)) outsideRefs.push(ref)
+        if (!fs.existsSync(target)) missingRefs.push(ref)
+      }
+      if (missingRefs.length) {
+        add("broken-reference", "warn", t("lint.brokenReference", { id: skill.id, refs: missingRefs.slice(0, 5).join(", ") }), {
+          skills: [skill.id],
+        })
+      }
+      if (outsideRefs.length) {
+        add(
+          "reference-outside-skill",
+          "info",
+          t("lint.referenceOutside", { id: skill.id, refs: outsideRefs.slice(0, 5).join(", ") }),
+          { skills: [skill.id] },
+        )
+      }
+    }
+
     if (skill.bodyTokens > 4000) {
       add("large-body", "warn", t("lint.largeBody", { id: skill.id, tokens: skill.bodyTokens }), {
         skills: [skill.id],

package/src/mcp.mjs

@@ -1,4 +1,5 @@
 import { auditSkills, formatMarkdown } from "./audit.mjs"
+import { writeHtmlReport } from "./html.mjs"
 import { normalizeLang, detectLang } from "./i18n.mjs"
 
 export const PROTOCOL_VERSION = "2025-06-18"
@@ -30,6 +31,10 @@ export function toolDefinition() {
           type: "boolean",
           description: "Include global skill directories such as ~/.config/opencode and ~/.claude (default true)",
         },
+        html: {
+          type: "string",
+          description: "Optional path; when set, a self-contained HTML report is written there and the path is returned",
+        },
       },
       additionalProperties: false,
     },
@@ -86,7 +91,12 @@ export async function handleMessage(message, { version = "0.0.0" } = {}) {
         const lang = normalizeLang(args.lang) ?? detectLang()
 
         const audit = auditSkills({ cwd: directory, budget, lang, includeGlobal: args.global !== false })
-        return ok(id, { content: [{ type: "text", text: formatMarkdown(audit) }] })
+        let text = formatMarkdown(audit)
+        if (typeof args.html === "string" && args.html.trim()) {
+          const file = writeHtmlReport(audit, args.html.trim(), { title: "skills-doctor report" })
+          text += `\n\nHTML report written to \`${file}\``
+        }
+        return ok(id, { content: [{ type: "text", text }] })
       }
 
       default:

package/src/plugin-v1.mjs

@@ -1,5 +1,6 @@
 import { tool } from "@opencode-ai/plugin"
 import { auditSkills, formatMarkdown } from "./audit.mjs"
+import { writeHtmlReport } from "./html.mjs"
 import { budgetWarning } from "./warning.mjs"
 
 const z = tool.schema
@@ -18,11 +19,17 @@ export const SkillsDoctorPlugin = async ({ directory }) => ({
       args: z.object({
         directory: z.string().optional().describe("Directory to audit (defaults to the current project)"),
         budget: z.number().optional().describe("Description token budget (default 1200)"),
+        html: z.string().optional().describe("Optional path; when set, a self-contained HTML report is written there"),
       }),
       execute: async (args) => {
         const cwd = args.directory || directory || process.cwd()
         const audit = auditSkills({ cwd, budget: typeof args.budget === "number" ? args.budget : null, lang: "en" })
-        return formatMarkdown(audit)
+        let markdown = formatMarkdown(audit)
+        if (typeof args.html === "string" && args.html.trim()) {
+          const file = writeHtmlReport(audit, args.html.trim(), { title: "skills-doctor report" })
+          markdown += `\n\nHTML report written to \`${file}\``
+        }
+        return markdown
       },
     }),
   },

package/src/plugin.mjs

@@ -1,5 +1,6 @@
 import { Plugin } from "@opencode/plugin"
 import { auditSkills, formatMarkdown } from "./audit.mjs"
+import { writeHtmlReport } from "./html.mjs"
 import { budgetWarning } from "./warning.mjs"
 
 /**
@@ -22,6 +23,10 @@ export default Plugin.define({
           properties: {
             directory: { type: "string", description: "Directory to audit (defaults to the current project)" },
             budget: { type: "number", description: "Description token budget (default 1200)" },
+            html: {
+              type: "string",
+              description: "Optional path; when set, a self-contained HTML report is written there",
+            },
           },
           additionalProperties: false,
         },
@@ -30,7 +35,12 @@ export default Plugin.define({
           const directory = (input && typeof input.directory === "string" && input.directory) || ctx.location.directory
           const budget = input && typeof input.budget === "number" ? input.budget : null
           const audit = auditSkills({ cwd: directory, budget, lang: "en" })
-          return { content: formatMarkdown(audit) }
+          let markdown = formatMarkdown(audit)
+          if (input && typeof input.html === "string" && input.html.trim()) {
+            const file = writeHtmlReport(audit, input.html.trim(), { title: "skills-doctor report" })
+            markdown += `\n\nHTML report written to \`${file}\``
+          }
+          return { content: markdown }
         },
       })
     })
@@ -48,6 +58,18 @@ export default Plugin.define({
           })
         },
       })
+      editor.add({
+        name: "skills-report",
+        description: "Write a self-contained HTML skills report to a path you choose",
+        execute: async ({ sessionID, prompt, delivery }) => {
+          await ctx.session.prompt({
+            ...prompt,
+            sessionID,
+            text: "Ask me where to save the HTML report (a file path, default ./skills-report.html), then call the skills_doctor tool with the html argument set to that path and tell me where it was written.",
+            delivery,
+          })
+        },
+      })
     })
 
     // 每个会话最多注入一次预算预警，避免刷屏

package/src/refs.mjs

@@ -0,0 +1,40 @@
+const URL_LIKE = /^(?:[a-z][a-z0-9+.-]*:|#|\/|~)/i
+const GLOB_LIKE = /[*?[\]{}]/
+
+function cleanTarget(raw) {
+  let target = String(raw ?? "").trim()
+  if (!target) return null
+  if (target.startsWith("<") && target.endsWith(">")) target = target.slice(1, -1).trim()
+  target = target.split("#")[0].split("?")[0].trim()
+  if (!target) return null
+  return target
+}
+
+/**
+ * 从 SKILL.md 正文里提取「看起来是相对文件路径」的引用：
+ * - markdown 链接 [x](path)
+ * - 行内代码 `references/foo.md`
+ * 跳过 URL、绝对路径、~/、占位符、glob。
+ */
+export function extractReferences(body) {
+  const refs = new Set()
+
+  const add = (raw) => {
+    let target = cleanTarget(raw)
+    if (!target) return
+    if (URL_LIKE.test(target)) return
+    if (GLOB_LIKE.test(target)) return
+    if (target.includes("<") || target.includes(">") || target.includes("${")) return
+    if (target.startsWith("$") || target.startsWith("-")) return
+    if (/\s/.test(target)) return
+
+    const looksLikePath = target.includes("/") || /\.(md|markdown|sh|bash|py|ts|js|mjs|cjs|json|ya?ml|toml|txt|svg|png|jpe?g|gif|webp|csv)$/i.test(target)
+    if (!looksLikePath) return
+    refs.add(target)
+  }
+
+  for (const match of String(body ?? "").matchAll(/\]\(\s*([^)\s]+)\s*\)/g)) add(match[1])
+  for (const match of String(body ?? "").matchAll(/`([^`\n]+)`/g)) add(match[1])
+
+  return [...refs]
+}