opencode-skills-doctor 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wangyuchen5110
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,177 @@
-# Temporary Holding Version
+# skills-doctor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![test](https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml/badge.svg)](https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml)
+
+Local scanner, linter, fixer, updater and **OpenCode plugin** for skills — zero dependencies, Node ≥ 20.
+
+**English** | [简体中文](README.zh-CN.md)
+
+## Why
+
+On every model step, OpenCode advertises every skill that has a `description` — the model sees `ID + name + description` for each of them. As skills pile up, this turns into **context bloat, colliding descriptions, shadowed IDs, edits to the wrong file, and skills that silently stop working**.
+
+`skills-doctor` surfaces all of that locally, and can also update skills from an HTTP catalog and verify the result.
+
+## Quick start
+
+```powershell
+# Run straight from the repo (no install)
+node bin/skills-doctor.mjs check
+
+# Or install it locally
+npm link
+skills-doctor check
+```
+
+## Commands
+
+All commands accept `--lang en|zh` (default: auto from the system locale) and `--json`.
+
+### `check` (default)
+
+Scans every skill source, reports problems, the context budget and fix hints.
+
+```powershell
+skills-doctor check
+skills-doctor check --json
+skills-doctor check --budget 800 --strict    # for CI
+skills-doctor check --root .\some-project --no-global
+```
+
+### `scan`
+
+Lists every skill with its source, precedence, whether the model can see it, and token cost.
+
+```powershell
+skills-doctor scan
+```
+
+`*` marks the definition that actually wins (later registration = higher precedence).
+
+### `fix`
+
+Archives definitions that are shadowed — files that never load because another source defines the same ID. The move is reversible: files go into `.skills-doctor-archive/<timestamp>/` inside the same source, which OpenCode ignores (dot-directory).
+
+```powershell
+skills-doctor fix --dry-run   # preview what would be archived
+skills-doctor fix
+skills-doctor fix --hide academic-paper,deep-research --dry-run   # hide low-frequency skills
+```
+
+- Only shadowed duplicates are touched; the effective definition is never moved;
+- Files installed by `update` are skipped — use `update` to bring them back;
+- After fixing, `check` should report no `shadowed` findings.
+
+### `update` (updater)
+
+Reads HTTP catalogs from the `skills` array in `opencode.json(c)`, compares `version`, and downloads whatever changed.
+
+```powershell
+skills-doctor update                 # installs into .opencode/skills by default (where opencode reads)
+skills-doctor update --check-only    # only report available updates
+skills-doctor update --into .\team-skills
+```
+
+- The output directory is a real OpenCode skill directory, so **`check` picks the update up immediately**;
+- Writes `.skills-doctor.lock.json` (schema v2: a sha1 for every file);
+- `check` reads that lock: shows managed versions, detects hand edits (`managed-drift`) and missing files (`managed-missing`);
+- Running `update` again re-downloads drifted files (self-healing).
+
+## Configuration
+
+Optional `.skills-doctor.json` in the working directory (or pass `--config <file>`):
+
+```json
+{
+  "budget": 1200,
+  "staleDays": 180,
+  "lang": "en",
+  "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.
+
+## OpenCode plugin
+
+The package also exports an OpenCode 2.x plugin:
+
+```jsonc
+// opencode.jsonc
+{
+  "plugins": ["opencode-skills-doctor"]
+}
+```
+
+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.
+
+`@opencode/plugin` is an optional peer dependency; OpenCode provides it at runtime.
+
+## Rules
+
+| Rule | Level | Meaning |
+|---|---|---|
+| `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 |
+| `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) |
+| `token-budget` | warn/error | Total advertised description tokens exceed the budget (default 1200) |
+| `too-many-skills` | warn/error | More than 60 / 100 skills are advertised |
+| `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` |
+| `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 |
+| `lock-version-unsupported` | info | Lock is newer than this tool; parsed in compatibility mode |
+
+## Forward compatibility
+
+- **Lock**: supports v1 (string versions, no hashes) and v2 (per-file sha1). A newer lock version is parsed in compatibility mode, unknown fields are ignored, and a single `lock-version-unsupported` notice is emitted.
+- **Catalog `index.json`**: only `skills[].name/version/files` is read; any future fields are ignored.
+- **Skill frontmatter**: only `name`, `description`, `metadata.opencode/autoinvoke` and `disable-model-invocation` are read; everything else is ignored.
+- **Paths**: both OpenCode 2.0 locations (`.opencode/skills`, `~/.config/opencode/skills`) and compatibility locations (`.claude/skills`, `.agents/skills`, searched upward level by level).
+- The updater always writes the highest lock version this tool supports, so older readers never break on new fields.
+
+## Discovery sources (low → high precedence)
+
+1. `~/.claude/skills`
+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)` (relative paths resolve from the working directory; supports `~/`, absolute paths and HTTP catalogs)
+
+## JSON output
+
+`check --json`, `scan --json` and `update --json` all print structured JSON, ready for CI or a web report. Fields include `summary`, `findings[]` and `skills[]` (with `managed: { version, url, root }`).
+
+## Known limitations
+
+- `check` is offline; use `update --check-only` to ask a catalog for new versions.
+- Token counts are heuristic (CJK ≈ 1.7 chars/token, the rest ≈ 4 chars/token) — good for comparisons, not for billing.
+- Config precedence is assumed: global config < project config < `skills` array order. If OpenCode differs, trust the runtime.
+- No automatic file rewriting yet (v0.2 plans `--fix`: archive shadowed definitions, normalize IDs, trim descriptions).
+
+## Roadmap
+
+- v0.4: content-aware suggestions (which skills are never used), catalog signature verification
+- Later: V1/Claude skill migration report
+
+## Development
+
+```powershell
+npm test
+```
+
+Coverage: frontmatter parsing, source discovery and precedence, shadowing/duplication/budget rules, catalog download and lock, drift detection and self-healing, old/new lock compatibility, CLI JSON output and exit codes.
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,177 @@
+# skills-doctor
+
+[![test](https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml/badge.svg)](https://github.com/wangyuchen5110/opencodeplugginprogram/actions/workflows/test.yml)
+
+OpenCode skill 的**本地检测器 + 更新器 + 修复器**，并附带 **OpenCode 插件入口** —— 零依赖，Node ≥ 20。
+
+[English](README.md) | **简体中文**
+
+## 为什么需要它
+
+opencode 每个模型步骤都会把所有「有 description 的 skill」展示给模型（`ID + name + description`）。skill 一多、一杂，就会出现**上下文膨胀、描述撞车、同 ID 互相遮蔽、改错文件、静默失效**。
+
+`skills-doctor` 在本地把这些都查出来，并且能从 HTTP catalog 更新 skill、校验更新结果。
+
+## 快速开始
+
+```powershell
+# 直接在仓库里跑（免安装）
+node bin/skills-doctor.mjs check
+
+# 或本地安装
+npm link
+skills-doctor check
+```
+
+## 命令
+
+所有命令都支持 `--lang en|zh`（默认按系统 locale 自动选择）和 `--json`。
+
+### `check`（默认）
+
+扫描所有 skill 来源，输出问题清单、上下文预算和修复建议。
+
+```powershell
+skills-doctor check
+skills-doctor check --json
+skills-doctor check --budget 800 --strict    # CI 用
+skills-doctor check --root .\some-project --no-global
+```
+
+### `scan`
+
+列出所有 skill 及其来源、优先级、是否会被模型看到、token 占用。
+
+```powershell
+skills-doctor scan
+```
+
+`*` 表示该 ID 的实际生效定义（注册顺序越后优先级越高）。
+
+### `fix`
+
+归档被遮蔽的定义——那些因为同 ID 已被更高优先级来源覆盖、永远不会加载的文件。操作可逆：文件会被移动到同一来源下的 `.skills-doctor-archive/<时间戳>/`，opencode 不会读取点目录。
+
+```powershell
+skills-doctor fix --dry-run   # 预览会归档哪些
+skills-doctor fix
+skills-doctor fix --hide academic-paper,deep-research --dry-run   # 隐藏低频 skill，给预算减压
+```
+
+- 只动被遮蔽的重复定义，生效版本永远不会被移动；
+- 由 `update` 安装的文件会跳过——用 `update` 恢复；
+- 修完再跑 `check`，`shadowed` 应该消失。
+
+### `update`（更新器）
+
+从 `opencode.json(c)` 的 `skills` 数组里读取 HTTP catalog，对比 `version`，把有变化的 skill 下载到本地。
+
+```powershell
+skills-doctor update                 # 默认装进 .opencode/skills（opencode 会直接读取）
+skills-doctor update --check-only    # 只看有没有更新
+skills-doctor update --into .\team-skills
+```
+
+- 落盘位置就是 opencode 的 skill 目录 → **更新完 `check` 立刻能检测到**；
+- 写 `.skills-doctor.lock.json`（v2：记录每个文件的 sha1）；
+- `check` 会读这个 lock：显示托管版本、发现文件被手改（`managed-drift`）、文件被删（`managed-missing`）；
+- 再跑一次 `update` 会自动重下被改坏的文件（drift 自愈）。
+
+## 配置
+
+在工作目录放一个可选的 `.skills-doctor.json`（或用 `--config <file>` 指定）：
+
+```json
+{
+  "budget": 1200,
+  "staleDays": 180,
+  "lang": "en",
+  "rules": { "long-description": "off", "hidden-skill": "info" },
+  "ignore": ["legacy-skill"]
+}
+```
+
+`rules` 接受 `off` / `info` / `warn` / `error`；`ignore` 会丢掉只涉及这些 ID 的 finding。命令行参数优先级高于配置文件。
+
+## OpenCode 插件
+
+这个包同时导出 OpenCode 2.x 插件：
+
+```jsonc
+// opencode.jsonc
+{
+  "plugins": ["opencode-skills-doctor"]
+}
+```
+
+它会注册：
+
+- `skills_doctor` 工具（命名空间 `skills`）—— agent 传 `{ directory?, budget? }` 就能拿到 markdown 审计报告；
+- `/skills-doctor` 命令 —— 让 agent 跑一次审计并总结修复建议。
+
+`@opencode/plugin` 是可选 peer 依赖，运行时由 OpenCode 提供。
+
+## 检测规则
+
+| 规则 | 级别 | 含义 |
+|---|---|---|
+| `shadowed` | warn | 同一 ID 多处定义，只有一份生效，其余白占体积且容易改错 |
+| `flat-dir-collision` | warn | 同一来源同时存在 `<id>.md` 和 `<id>/SKILL.md` |
+| `duplicate-content` | warn | 不同 skill 正文完全相同 |
+| `near-duplicate-description` | warn | 两个 skill 的 description 相似度 ≥ 75%，模型容易选错 |
+| `missing-description` | info | 没有 description，模型看不到它 |
+| `long-description` | warn | description > 240 字符（每个模型步骤都占上下文） |
+| `large-body` | warn | 正文 > 4000 tokens（调用时整段进上下文） |
+| `token-budget` | warn/error | 模型每步要看的描述总量超过预算（默认 1200） |
+| `too-many-skills` | warn/error | 展示给模型的 skill 超过 60 / 100 个 |
+| `invalid-id` | info | 不符合 kebab-case 规范 |
+| `hidden-skill` | info | 被 `opencode/autoinvoke: false` 或 `disable-model-invocation: true` 隐藏 |
+| `stale-skill` | info | `--stale-days` 指定的天数内没更新 |
+| `managed-drift` | warn | 由 update 安装的文件在更新后被改过 |
+| `managed-missing` | warn | lock 里记录了，但本地文件没了 |
+| `managed-unsafe` | warn | lock 里有路径穿越等不安全路径 |
+| `lock-version-unsupported` | info | lock 版本比工具新，已按兼容模式解析 |
+
+## 向上兼容（forward compatibility）
+
+- **lock**：支持版本 1（字符串版本、无哈希）和版本 2（带文件 sha1）；遇到更高版本时按兼容模式解析，未知字段忽略，只在报告里提示一条 `lock-version-unsupported`。
+- **catalog index.json**：只读 `skills[].name/version/files`，其余字段（未来新增的）一律忽略。
+- **skill frontmatter**：只读 `name/description/metadata.opencode/autoinvoke/disable-model-invocation`，其它字段原样忽略。
+- **路径**：同时支持 2.0 的 `.opencode/skills`、`~/.config/opencode/skills`，以及兼容目录 `.claude/skills`、`.agents/skills`（含逐级向上搜索）。
+- 更新器写出的 lock 固定为当前支持的最高版本，旧检测器不会因为新字段报错。
+
+## 扫描来源（低 → 高优先级）
+
+1. `~/.claude/skills`
+2. 项目 `.claude/skills`（项目根 → 当前目录逐级）
+3. `~/.agents/skills`
+4. 项目 `.agents/skills`
+5. `~/.config/opencode/skills`
+6. 项目 `.opencode/skills`
+7. `opencode.json(c)` 的 `skills` 数组（相对路径按当前工作目录解析，支持 `~/`、绝对路径、HTTP catalog）
+
+## JSON 输出
+
+`check --json` / `scan --json` / `update --json` 都会输出结构化 JSON，方便接 CI 或做网页报告。字段包括 `summary`、`findings[]`、`skills[]`（含 `managed: { version, url, root }`）。
+
+## 已知限制
+
+- 不联网时 `check` 只做本地检查；catalog 是否有新版本要用 `update --check-only`。
+- token 估算是启发式（CJK 约 1.7 字/token，其余约 4 字符/token），用于横向比较，不是精确计费。
+- 配置优先级假设：全局配置 < 项目配置 < `skills` 数组顺序；如与 opencode 实现有出入，以实际加载结果为准。
+- 还不会自动改文件（v0.2 计划加 `--fix`：归档被遮蔽的定义、规范化 ID、裁剪描述）。
+
+## Roadmap
+
+- v0.4：内容层面的建议（哪些 skill 从未被使用）、catalog 签名校验
+- 后续：V1/Claude skill 兼容迁移报告
+
+## 开发
+
+```powershell
+npm test
+```
+
+测试覆盖：frontmatter 解析、来源发现与优先级、遮蔽/重复/预算规则、catalog 下载与 lock、drift 检测与自愈、旧/新 lock 的向上兼容、CLI JSON 与退出码。
+
+MIT

package/bin/skills-doctor.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.mjs"
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(`skills-doctor 出错: ${err?.message ?? err}`)
+  process.exit(2)
+})

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Local scanner, linter, fixer and updater for OpenCode skills, with an OpenCode plugin entry",
+  "type": "module",
+  "exports": {
+    ".": "./src/plugin.mjs",
+    "./plugin": "./src/plugin.mjs"
+  },
+  "bin": {
+    "skills-doctor": "./bin/skills-doctor.mjs"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode/plugin": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node test/doctor.test.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "README.zh-CN.md"
+  ],
+  "keywords": [
+    "opencode",
+    "skills",
+    "lint",
+    "fix",
+    "cli",
+    "plugin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wangyuchen5110/opencodeplugginprogram.git"
+  },
+  "license": "MIT"
+}

package/src/audit.mjs

@@ -0,0 +1,93 @@
+import path from "node:path"
+import { discoverSources, scanAll } from "./discover.mjs"
+import { lint, summarize, SEVERITY_ORDER } from "./lint.mjs"
+import { inspectManaged } from "./managed.mjs"
+import { loadConfig } from "./config.mjs"
+import { translator, normalizeLang, detectLang } from "./i18n.mjs"
+
+/**
+ * 一次完整审计：扫描来源 → 检测 → 托管校验。
+ * CLI、插件、脚本共用同一个入口。
+ */
+export function auditSkills({
+  cwd = process.cwd(),
+  includeGlobal = true,
+  lang = null,
+  configPath = null,
+  budget = null,
+  staleDays = null,
+} = {}) {
+  const loaded = loadConfig(cwd, configPath)
+  const config = loaded.config
+  const resolvedLang = normalizeLang(lang) ?? normalizeLang(config.lang) ?? detectLang()
+  const t = translator(resolvedLang)
+
+  const discovered = scanAll(discoverSources({ cwd, includeGlobal }))
+  const managedInfo = inspectManaged(discovered.scans, { t })
+
+  const effectiveBudget = Number.isFinite(budget) && budget > 0 ? budget : config.budget ?? 1200
+  const effectiveStale = Number.isFinite(staleDays) && staleDays >= 0 ? staleDays : config.staleDays ?? 0
+
+  const findings = [
+    ...lint(discovered.skills, {
+      budget: effectiveBudget,
+      staleDays: effectiveStale,
+      ruleOverrides: config.rules,
+      ignore: config.ignore,
+      t,
+    }),
+    ...managedInfo.findings,
+  ].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity])
+
+  const summary = summarize(discovered.skills)
+  const counts = {
+    errors: findings.filter((f) => f.severity === "error").length,
+    warnings: findings.filter((f) => f.severity === "warn").length,
+    infos: findings.filter((f) => f.severity === "info").length,
+  }
+
+  return {
+    cwd: path.resolve(cwd),
+    projectRoot: discovered.projectRoot,
+    lang: resolvedLang,
+    config: { file: loaded.file, error: loaded.error ?? null, ...config },
+    budget: effectiveBudget,
+    staleDays: effectiveStale,
+    sources: discovered.sources,
+    catalogs: discovered.catalogs,
+    missing: discovered.missing,
+    skills: discovered.skills,
+    managed: managedInfo.managed,
+    summary,
+    findings,
+    counts,
+  }
+}
+
+/** 把审计结果渲染成适合给 agent / PR 评论用的 markdown。 */
+export function formatMarkdown(audit, { limit = 25 } = {}) {
+  const lines = []
+  lines.push("# skills-doctor")
+  lines.push("")
+  lines.push(`Workdir: \`${audit.cwd}\``)
+  lines.push(
+    `Skills: ${audit.summary.total} definitions, ${audit.summary.unique} unique IDs, ` +
+      `${audit.summary.advertised} advertised, ~${audit.summary.advertisedTokens} description tokens (budget ${audit.budget})`,
+  )
+  lines.push("")
+
+  if (!audit.findings.length) {
+    lines.push("No problems found.")
+    return lines.join("\n")
+  }
+
+  lines.push(`Findings: ${audit.counts.errors} error, ${audit.counts.warnings} warn, ${audit.counts.infos} info`)
+  lines.push("")
+  for (const finding of audit.findings.slice(0, limit)) {
+    lines.push(`- **${finding.severity}** \`${finding.rule}\` — ${finding.message}`)
+  }
+  if (audit.findings.length > limit) lines.push(`- …and ${audit.findings.length - limit} more`)
+  lines.push("")
+  lines.push("Next: run `npx opencode-skills-doctor fix` to archive shadowed definitions, or hide low-frequency skills.")
+  return lines.join("\n")
+}