opencode-skills-doctor 0.3.15 → 0.4.1

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.
@@ -143,6 +157,30 @@ Local execution is free, but any tool registered with the model is visible on ev
 
 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.
 
+## Self-update
+
+`skills-doctor` checks npm for a newer version of itself at most once per 24 hours (skipped in CI, non-TTY and `--json` runs):
+
+```powershell
+skills-doctor upgrade            # check now
+skills-doctor upgrade --open     # check and open the GitHub release page
+skills-doctor upgrade --apply    # npm install -g opencode-skills-doctor@latest
+```
+
+Opt out permanently in `.skills-doctor.json`:
+
+```json
+{ "checkUpdates": "off" }
+```
+
+| Value | Behavior |
+|---|---|
+| `"notify"` (default) | print a one-line notice when a newer version exists |
+| `"open"` | same, plus opens the release page in the browser |
+| `"off"` | never check |
+
+Per run: `--no-update-check`. Per environment: `SKILLS_DOCTOR_UPDATE_CHECK=0`. The plugin injects the same notice into the system prompt once per session when an update exists. Cached state lives in `~/.skills-doctor/self-update.json`.
+
 ## Configuration
 
 Optional `.skills-doctor.json` in the working directory (or pass `--config <file>`):
@@ -152,12 +190,13 @@ Optional `.skills-doctor.json` in the working directory (or pass `--config <file
   "budget": 1200,
   "staleDays": 180,
   "lang": "en",
+  "checkUpdates": "notify",
   "rules": { "long-description": "off", "hidden-skill": "info" },
   "ignore": ["legacy-skill"]
 }
 ```
 
-`rules` accepts `off`, `info`, `warn` or `error`; `ignore` drops findings that only involve those IDs. CLI flags override the file.
+`rules` accepts `off`, `info`, `warn` or `error`; `ignore` drops findings that only involve those IDs; `checkUpdates` is `notify` / `open` / `off`. CLI flags override the file.
 
 ## OpenCode plugin
 
@@ -172,8 +211,10 @@ The package also exports an OpenCode 2.x plugin:
 
 It registers:
 
-- the `skills_doctor` tool (namespace `skills`) — the agent can audit with `{ directory?, budget? }` and gets a markdown report;
-- the `/skills-doctor` command — asks the agent to run the audit and summarize fixes.
+- 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;
+- `/skills-upgrade` — checks whether skills-doctor itself has a newer version.
 
 `@opencode/plugin` is an optional peer dependency; OpenCode provides it at runtime.
 
@@ -221,8 +262,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 +347,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 +374,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 +397,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 占用。
@@ -143,6 +157,30 @@ skills-doctor update --into .\team-skills
 
 所以插件是用固定的少量开销，换「模型能自己体检」。上面的例子里 skill 描述每步 3074 tokens，压到 1200 预算能省下 10 倍于插件开销的 token。想要**零上下文成本**，就别装插件——用 `npx opencode-skills-doctor check` 在终端或 CI 里跑。
 
+## 自更新
+
+`skills-doctor` 最多每 24 小时查一次 npm 上自己有没有新版本（CI、非 TTY、`--json` 时自动跳过）：
+
+```powershell
+skills-doctor upgrade            # 立即检查
+skills-doctor upgrade --open     # 检查并打开 GitHub Release 页面
+skills-doctor upgrade --apply    # npm install -g opencode-skills-doctor@latest
+```
+
+在 `.skills-doctor.json` 里永久关闭：
+
+```json
+{ "checkUpdates": "off" }
+```
+
+| 取值 | 行为 |
+|---|---|
+| `"notify"`（默认） | 有新版本时打印一行提示 |
+| `"open"` | 提示 + 自动打开 Release 页面 |
+| `"off"` | 完全不检查 |
+
+单次关闭：`--no-update-check`；环境变量：`SKILLS_DOCTOR_UPDATE_CHECK=0`。插件在有新版本时会把提示注入系统提示（每个会话一次）。检查缓存位于 `~/.skills-doctor/self-update.json`。
+
 ## 配置
 
 在工作目录放一个可选的 `.skills-doctor.json`（或用 `--config <file>` 指定）：
@@ -152,12 +190,13 @@ skills-doctor update --into .\team-skills
   "budget": 1200,
   "staleDays": 180,
   "lang": "en",
+  "checkUpdates": "notify",
   "rules": { "long-description": "off", "hidden-skill": "info" },
   "ignore": ["legacy-skill"]
 }
 ```
 
-`rules` 接受 `off` / `info` / `warn` / `error`；`ignore` 会丢掉只涉及这些 ID 的 finding。命令行参数优先级高于配置文件。
+`rules` 接受 `off` / `info` / `warn` / `error`；`ignore` 会丢掉只涉及这些 ID 的 finding；`checkUpdates` 取 `notify` / `open` / `off`。命令行参数优先级高于配置文件。
 
 ## OpenCode 插件
 
@@ -172,8 +211,10 @@ skills-doctor update --into .\team-skills
 
 它会注册：
 
-- `skills_doctor` 工具（命名空间 `skills`）—— agent 传 `{ directory?, budget? }` 就能拿到 markdown 审计报告；
-- `/skills-doctor` 命令 —— 让 agent 跑一次审计并总结修复建议。
+- `skills_doctor` 工具（命名空间 `skills`）—— agent 传 `{ directory?, budget?, html? }` 就能拿到 markdown 审计报告；
+- `/skills-doctor` 命令 —— 让 agent 跑一次审计并总结修复建议；
+- `/skills-report` —— 先问你要把 HTML 报告存到哪里，再写文件；
+- `/skills-upgrade` —— 检查 skills-doctor 自身有没有新版本。
 
 `@opencode/plugin` 是可选 peer 依赖，运行时由 OpenCode 提供。
 
@@ -221,8 +262,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 +347,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 +374,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 +397,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.15",
-  "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.1",
+  "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,15 @@ 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 {
+  checkForUpdate,
+  resolveMode,
+  upgradeCommand,
+  applyUpgrade,
+  openReleasePage,
+  RELEASES_URL,
+} from "./self-update.mjs"
 import { padDisplay } from "./parse.mjs"
 import { detectLang, normalizeLang, translator } from "./i18n.mjs"
 
@@ -38,6 +47,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,12 +72,16 @@ function parseArgs(argv) {
     prune: false,
     configDir: null,
     noNpm: false,
+    html: null,
+    open: false,
+    apply: false,
+    updateCheck: true,
     help: false,
     version: false,
   }
 
   const args = [...argv]
-  const commands = new Set(["check", "scan", "update", "fix", "install", "uninstall", "mcp", "help"])
+  const commands = new Set(["check", "scan", "update", "fix", "install", "uninstall", "upgrade", "mcp", "help"])
   if (args[0] && commands.has(args[0])) {
     options.command = args.shift()
   }
@@ -125,6 +142,25 @@ 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
+      case "--no-update-check":
+        options.updateCheck = false
+        break
       case "-h":
       case "--help":
         options.help = true
@@ -426,6 +462,27 @@ function runFix(audit, options, t) {
   return errors.length ? 1 : 0
 }
 
+async function maybeNotifyUpdate({ options, config, t }) {
+  if (!options.updateCheck) return
+  if (options.json || !process.stdout.isTTY || process.env.CI) return
+  const mode = resolveMode(config)
+  if (mode === "off") return
+  const update = await checkForUpdate({ current: pkg.version, mode })
+  if (!update) return
+  console.log("")
+  console.log(
+    dim(
+      t("update.toolAvailable", {
+        latest: update.latest,
+        current: pkg.version,
+        cmd: "npx opencode-skills-doctor@latest check",
+        url: update.url,
+      }),
+    ),
+  )
+  if (mode === "open") openReleasePage({ url: update.url })
+}
+
 export async function main(argv) {
   const options = parseArgs(argv)
 
@@ -497,6 +554,44 @@ export async function main(argv) {
     return
   }
 
+  if (options.command === "upgrade") {
+    const update = await checkForUpdate({ current: pkg.version, force: true })
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            current: pkg.version,
+            latest: update?.latest ?? pkg.version,
+            updateAvailable: Boolean(update),
+            url: update?.url ?? RELEASES_URL,
+            command: upgradeCommand(),
+          },
+          null,
+          2,
+        ),
+      )
+    } else {
+      console.log(bold(t("upgrade.title")))
+      console.log(dim(t("upgrade.current", { version: pkg.version })))
+      if (update) {
+        console.log(t("upgrade.available", { latest: update.latest, current: pkg.version }))
+        console.log(dim(t("upgrade.command", { cmd: upgradeCommand() })))
+        console.log(dim(t("upgrade.open", { url: update.url })))
+        if (options.open) openReleasePage({ url: update.url })
+        if (options.apply) {
+          if (applyUpgrade()) console.log(green(t("upgrade.done")))
+          else {
+            console.log(red(t("upgrade.failed", { cmd: upgradeCommand() })))
+            process.exitCode = 1
+          }
+        }
+      } else {
+        console.log(green(t("upgrade.upToDate")))
+      }
+    }
+    return
+  }
+
   if (options.command === "check") {
     const audit = auditSkills({
       cwd,
@@ -506,21 +601,28 @@ 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 })))
+      await maybeNotifyUpdate({ options, config: loaded.config, t })
     }
-    process.exitCode = buildCheckResult(audit, options).exitCode
+    process.exitCode = result.exitCode
     return
   }
 
@@ -545,6 +647,7 @@ export async function main(argv) {
       return
     }
     printScan(discovered, options, managedInfo.managed, t)
+    await maybeNotifyUpdate({ options, config: loaded.config, t })
     return
   }
 

package/src/config.mjs

@@ -15,6 +15,10 @@ function normalize(raw) {
     }
   }
   if (Array.isArray(raw?.ignore)) config.ignore = raw.ignore.filter((id) => typeof id === "string")
+  const checkUpdates = raw?.checkUpdates ?? raw?.updateCheck
+  if (checkUpdates === false || checkUpdates === "off") config.checkUpdates = "off"
+  else if (checkUpdates === true) config.checkUpdates = "notify"
+  else if (checkUpdates === "notify" || checkUpdates === "open") config.checkUpdates = checkUpdates
   return config
 }
 

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),