opencode-skills-doctor 0.9.3 → 0.9.6

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>Audit the token cost your coding agent pays for skills on every step.</b><br>
+  A word-piece estimate, boilerplate-aware overlap, and a plan that keeps the routing sentence and hides the redundant skill first.
 </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">
@@ -47,7 +48,7 @@ Every agent skill with a `description` is advertised to the model on **every sin
 | | |
 |---|---|
 | **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 |
 | **Run it** | CLI · OpenCode plugin (1.x/2.x/Desktop) · MCP server · DeepSeek Harness skill |
@@ -141,7 +142,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,7 +158,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: wangyuchen5110/opencodeplugginprogram@v0.9.3
+      - uses: wangyuchen5110/opencodeplugginprogram@v0.9.6
         with:
           budget: "1200"
           fail-on: warn             # error | warn | never
@@ -165,16 +167,25 @@ jobs:
 ```
 
 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`. Outputs:
-`exit-code`, `error-count`, `warning-count`, `advertised-tokens`. Anything else
-goes through `extra-args` (for example `--no-global`).
+on the pull request, and fails the job according to `fail-on`.
+
+| Input | Default | Purpose |
+|---|---|---|
+| `root` | `.` | Directory to audit |
+| `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`.
 
 ## Commands
 
 | 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 |
@@ -208,7 +219,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/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,7 +48,7 @@ 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 |
+| **能修** | 归档遮蔽定义（可逆）、先藏重复的 skill、方案只留路由用的第一句 |
 | **报告** | 终端、JSON，或自包含 HTML（`--html [file] --open`） |
 | **规划** | 精确 token 节省：精简描述 / 隐藏 skill，按 N 步折算 |
 | **成本** | CLI 0 token；插件工具定义约 191/步，另有每会话一次预警 |
@@ -487,7 +488,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 +561,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

@@ -17,7 +17,7 @@ Local scanner, linter, fixer, updater and **OpenCode plugin** for agent skills
 | **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
 
@@ -438,7 +438,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 +517,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 +552,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-doctor",
-  "version": "0.9.3",
+  "version": "0.9.6",
   "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.",
   "type": "module",
   "exports": {

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

package/src/fix.mjs

@@ -96,11 +96,39 @@ export function applyFixes(plan, { dryRun = false } = {}) {
   return { moved, errors }
 }
 
-/** 在 frontmatter 里把 metadata.opencode/autoinvoke 设为 false。 */
+/** 先写临时文件再替换，避免隐藏 skill 时把 SKILL.md 写到一半。 */
+function writeFileAtomic(target, data) {
+  const tmp = `${target}.${process.pid}-${Math.random().toString(16).slice(2)}.tmp`
+  fs.writeFileSync(tmp, data)
+  try {
+    fs.renameSync(tmp, target)
+    return
+  } catch (err) {
+    // Windows refuses to rename onto an existing file (EPERM / EEXIST).
+    if (err?.code !== "EPERM" && err?.code !== "EEXIST") {
+      try {
+        fs.rmSync(tmp, { force: true })
+      } catch {}
+      throw err
+    }
+  }
+  try {
+    fs.copyFileSync(tmp, target)
+  } finally {
+    try {
+      fs.rmSync(tmp, { force: true })
+    } catch {}
+  }
+}
+
+/** 在 frontmatter 里把 metadata.opencode/autoinvoke 设为 false。保留原来的换行符。 */
 export function setAutoinvokeFalse(text) {
-  const lines = text.split(/\r?\n/)
+  const source = String(text ?? "")
+  const newline = source.includes("\r\n") ? "\r\n" : "\n"
+  const lines = source.split(/\r?\n/)
   const snippet = ["metadata:", "  opencode/autoinvoke: false"]
-  if (lines[0]?.trim() !== "---") return ["---", ...snippet, "---", ...lines].join("\n")
+  const join = (parts) => parts.join(newline)
+  if (lines[0]?.trim() !== "---") return join(["---", ...snippet, "---", ...lines])
 
   let end = -1
   for (let i = 1; i < lines.length; i++) {
@@ -109,12 +137,12 @@ export function setAutoinvokeFalse(text) {
       break
     }
   }
-  if (end === -1) return ["---", ...snippet, "---", ...lines].join("\n")
+  if (end === -1) return join(["---", ...snippet, "---", ...lines])
 
   const fm = lines.slice(1, end)
   const metaIdx = fm.findIndex((line) => /^metadata\s*:/.test(line.trim()))
   if (metaIdx === -1) {
-    return [lines[0], ...fm, ...snippet, ...lines.slice(end)].join("\n")
+    return join([lines[0], ...fm, ...snippet, ...lines.slice(end)])
   }
 
   const metaIndent = fm[metaIdx].length - fm[metaIdx].trimStart().length
@@ -131,7 +159,7 @@ export function setAutoinvokeFalse(text) {
   }
   if (!replaced) block.unshift(" ".repeat(metaIndent + 2) + "opencode/autoinvoke: false")
 
-  return [lines[0], ...fm.slice(0, metaIdx + 1), ...block, ...fm.slice(j), ...lines.slice(end)].join("\n")
+  return join([lines[0], ...fm.slice(0, metaIdx + 1), ...block, ...fm.slice(j), ...lines.slice(end)])
 }
 
 /**
@@ -154,7 +182,7 @@ export function hideSkills(skills, ids, { dryRun = false } = {}) {
     try {
       if (!dryRun) {
         const text = fs.readFileSync(skill.file, "utf8")
-        fs.writeFileSync(skill.file, setAutoinvokeFalse(text), "utf8")
+        writeFileAtomic(skill.file, setAutoinvokeFalse(text))
       }
       changed.push({ id, file: skill.file })
     } catch (err) {

package/src/i18n.mjs

@@ -193,7 +193,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
       'Both {flat} and {dir} exist in the same source (ID "{id}"), semantics are ambiguous',
     "lint.duplicateContent": "These skills have identical bodies: {ids}",
     "lint.nearDuplicate":
-      '"{a}" and "{b}" descriptions are {score}% similar; the model may pick the wrong one',
+      '"{a}" and "{b}" overlap {score}% on {terms}; the model may pick the wrong one',
     "lint.missingDescription":
       '"{id}" has no description, so the model will not discover it (only explicit @{id})',
     "lint.longDescription": '"{id}" description is {chars} chars; it is paid on every model step',
@@ -420,7 +420,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
       'ID "{id}" 有 {count} 处定义，实际生效的是 {winner}；其余 {losers} 处被遮蔽（白占体积、容易改错文件）',
     "lint.flatDirCollision": '同一来源同时存在 {flat} 与 {dir}（ID 都是 "{id}"），语义不明确',
     "lint.duplicateContent": "这些 skill 的正文完全相同：{ids}",
-    "lint.nearDuplicate": '"{a}" 与 "{b}" 的描述相似度 {score}%，模型容易选错',
+    "lint.nearDuplicate": '"{a}" 与 "{b}" 在 {terms} 上重叠 {score}%，模型容易选错',
     "lint.missingDescription": '"{id}" 没有 description，模型不会发现它（只能 @{id} 手动加载）',
     "lint.longDescription": '"{id}" 的 description 有 {chars} 字符，每个模型步骤都会占上下文',
     "lint.hiddenSkill": '"{id}" 被隐藏（autoinvoke/disable-model-invocation），不会出现在模型列表里',

package/src/lint.mjs

@@ -1,27 +1,36 @@
 import fs from "node:fs"
 import path from "node:path"
-import { estimateTokens } from "./parse.mjs"
+import { advertisedStepTokens, distinctiveTokenSet } from "./parse.mjs"
 import { extractReferences } from "./refs.mjs"
 import { translator } from "./i18n.mjs"
 
 export const SEVERITY_ORDER = { error: 0, warn: 1, info: 2 }
 
 const ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/
-const NEAR_DUPLICATE_THRESHOLD = 0.75
+const JACCARD_THRESHOLD = 0.72
+const CONTAINMENT_THRESHOLD = 0.85
+const MIN_SHARED = 3
+const MIN_SIZE_RATIO = 0.5
 
-function tokenSet(text) {
-  const tokens = String(text ?? "")
-    .toLowerCase()
-    .split(/[^\p{L}\p{N}]+/u)
-    .filter((t) => t.length >= 2)
-  return new Set(tokens)
-}
-
-function jaccard(a, b) {
-  if (!a.size || !b.size) return 0
-  let inter = 0
-  for (const t of a) if (b.has(t)) inter++
-  return inter / (a.size + b.size - inter)
+/** 两个描述有多容易让模型选错。套话已在 distinctiveTokenSet 里去掉。 */
+export function pairOverlap(a, b) {
+  if (!a?.size || !b?.size) return { jaccard: 0, containment: 0, shared: 0, terms: [] }
+  const small = a.size <= b.size ? a : b
+  const large = small === a ? b : a
+  let shared = 0
+  const terms = []
+  for (const token of small) {
+    if (!large.has(token)) continue
+    shared++
+    if (terms.length < 4) terms.push(token)
+  }
+  if (!shared) return { jaccard: 0, containment: 0, shared: 0, terms: [] }
+  return {
+    jaccard: shared / (a.size + b.size - shared),
+    containment: shared / small.size,
+    shared,
+    terms,
+  }
 }
 
 function byId(skills) {
@@ -48,6 +57,7 @@ export function resolveWinners(skills) {
 }
 
 export function lint(skills, options = {}) {
+  existsCache.clear()
   const t = options.t ?? translator("en")
   const budget = options.budget ?? 1200
   const staleDays = options.staleDays ?? 0
@@ -146,7 +156,7 @@ export function lint(skills, options = {}) {
       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 (!pathExists(target)) missingRefs.push(ref)
       }
       if (missingRefs.length) {
         add("broken-reference", "warn", t("lint.brokenReference", { id: skill.id, refs: missingRefs.slice(0, 5).join(", ") }), {
@@ -178,10 +188,7 @@ export function lint(skills, options = {}) {
   // 4) 上下文预算（只算会被模型看到的）
   const advertised = [...winners.values()].filter((s) => s.advertised)
   const described = advertised.filter((s) => s.description)
-  const advertisedTokens = described.reduce(
-    (sum, s) => sum + estimateTokens(`${s.id} ${s.displayName} ${s.description}`),
-    0,
-  )
+  const advertisedTokens = described.reduce((sum, s) => sum + advertisedStepTokens(s), 0)
 
   if (advertisedTokens > budget * 2) {
     add("token-budget", "error", t("lint.tokenBudgetError", { tokens: advertisedTokens, budget }), {
@@ -203,28 +210,34 @@ export function lint(skills, options = {}) {
     })
   }
 
-  // 5) 描述近似（token 集合只算一次；按大小升序后用 Jaccard 上界提前结束）
+  // 5) 描述近似：丢掉套话后看 Jaccard，以及短描述是否被长描述包含。
+  // 按特征数升序，|a|/|b| 低于 MIN_SIZE_RATIO 后不可能再达到任一门槛。
   const withDesc = described
-    .map((skill) => ({ skill, tokens: tokenSet(skill.description) }))
-    .filter((entry) => entry.tokens.size > 0)
-    .sort((x, y) => x.tokens.size - y.tokens.size)
+    .map((skill) => ({ skill, tokens: distinctiveTokenSet(skill.description) }))
+    .filter((entry) => entry.tokens.size >= MIN_SHARED)
+    .sort((x, y) => x.tokens.size - y.tokens.size || x.skill.id.localeCompare(y.skill.id))
   const pairs = []
   for (let i = 0; i < withDesc.length; i++) {
     const a = withDesc[i]
     for (let j = i + 1; j < withDesc.length; j++) {
       const b = withDesc[j]
       if (a.skill.id === b.skill.id) continue
-      // 大小升序：a 为空集已过滤，|a|/|b| 随 j 单调下降，低于阈值后再无可能命中。
-      if (a.tokens.size / b.tokens.size < NEAR_DUPLICATE_THRESHOLD) break
-      const score = jaccard(a.tokens, b.tokens)
-      if (score >= NEAR_DUPLICATE_THRESHOLD) pairs.push({ a: a.skill.id, b: b.skill.id, score })
+      if (a.tokens.size / b.tokens.size < MIN_SIZE_RATIO) break
+      const overlap = pairOverlap(a.tokens, b.tokens)
+      if (overlap.shared < MIN_SHARED) continue
+      const byJaccard = overlap.jaccard >= JACCARD_THRESHOLD
+      const byContainment = overlap.containment >= CONTAINMENT_THRESHOLD
+      if (!byJaccard && !byContainment) continue
+      const score = Math.max(overlap.jaccard, overlap.containment)
+      pairs.push({ a: a.skill.id, b: b.skill.id, score, terms: overlap.terms.join(", ") })
     }
   }
+  pairs.sort((x, y) => y.score - x.score || x.a.localeCompare(y.a))
   for (const pair of pairs.slice(0, 15)) {
     add(
       "near-duplicate-description",
       "warn",
-      t("lint.nearDuplicate", { a: pair.a, b: pair.b, score: (pair.score * 100).toFixed(0) }),
+      t("lint.nearDuplicate", { a: pair.a, b: pair.b, score: (pair.score * 100).toFixed(0), terms: pair.terms }),
       { skills: [pair.a, pair.b] },
     )
   }
@@ -234,6 +247,16 @@ export function lint(skills, options = {}) {
 
 const SEVERITIES = new Set(["error", "warn", "info"])
 
+const existsCache = new Map()
+
+function pathExists(target) {
+  const cached = existsCache.get(target)
+  if (cached !== undefined) return cached
+  const ok = fs.existsSync(target)
+  existsCache.set(target, ok)
+  return ok
+}
+
 function applyOverrides(findings, options) {
   const overrides = options.ruleOverrides ?? {}
   const ignore = new Set(options.ignore ?? [])
@@ -261,9 +284,7 @@ export function summarize(skills) {
     advertised: advertised.length,
     hidden: [...winners.values()].filter((s) => s.hidden).length,
     shadowed: skills.length - winners.size,
-    advertisedTokens: advertised
-      .filter((s) => s.description)
-      .reduce((sum, s) => sum + estimateTokens(`${s.id} ${s.displayName} ${s.description}`), 0),
+    advertisedTokens: advertised.filter((s) => s.description).reduce((sum, s) => sum + advertisedStepTokens(s), 0),
     bodyTokens: skills.reduce((sum, s) => sum + s.bodyTokens, 0),
   }
 }

package/src/parse.mjs

@@ -105,13 +105,100 @@ export function parseYamlLite(lines) {
 }
 
 const CJK_CHAR = /[\u2e80-\u9fff\uac00-\ud7af\uf900-\ufaff\uff00-\uffef]/
-const CJK_ALL = /[\u2e80-\u9fff\uac00-\ud7af\uf900-\ufaff\uff00-\uffef]/g
 
-/** 粗略 token 估算：CJK 约 1.7 字/token，其余约 4 字符/token。 */
+function isCjkUnit(code) {
+  return (
+    (code >= 0x2e80 && code <= 0x9fff) ||
+    (code >= 0xac00 && code <= 0xd7af) ||
+    (code >= 0xf900 && code <= 0xfaff) ||
+    (code >= 0xff00 && code <= 0xffef)
+  )
+}
+
+function isAsciiWord(code) {
+  return (code >= 48 && code <= 57) || (code >= 65 && code <= 90) || (code >= 97 && code <= 122)
+}
+
+/** 一个英文词在 BPE 里通常是 1 个 token；超过 6 个字符后每 4 个字符再加 1。 */
+function latinWordTokens(length) {
+  if (length <= 6) return 1
+  return 1 + Math.ceil((length - 6) / 4)
+}
+
+/**
+ * 按词切分的 token 估算，比「字符数 / 4」接近模型的真实切法：
+ * - 空白不计
+ * - 每个 CJK 字符 1 token（Grok / Claude / GPT-4o 这一档）
+ * - 英文词 1 token 起，长词和长标识符按每 4 个额外字符加 1
+ * - 连字符会把标识符切开，标点各自计 1
+ */
 export function estimateTokens(text) {
   const str = String(text ?? "")
-  const cjk = (str.match(CJK_ALL) ?? []).length
-  return Math.ceil(cjk * 1.7 + (str.length - cjk) / 4)
+  let tokens = 0
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i)
+    if (code === 32 || code === 9 || code === 10 || code === 13) continue
+    if (isCjkUnit(code)) {
+      tokens++
+      continue
+    }
+    if (isAsciiWord(code)) {
+      let length = 0
+      while (i < str.length && isAsciiWord(str.charCodeAt(i))) {
+        length++
+        i++
+      }
+      i--
+      tokens += latinWordTokens(length)
+      continue
+    }
+    tokens++
+  }
+  return tokens
+}
+
+const STOPWORDS = new Set([
+  "a", "an", "the", "and", "or", "to", "of", "for", "in", "on", "with", "when", "use", "using", "used",
+  "this", "that", "skill", "skills", "user", "users", "want", "wants", "wanted", "please", "from", "into",
+  "by", "as", "is", "are", "be", "it", "its", "their", "your", "you", "if", "then", "than", "via", "over",
+  "about", "how", "what", "which", "can", "will", "just", "also", "not", "but", "at", "we", "our", "them",
+  "的", "了", "和", "与", "或", "在", "为", "用", "使用", "当", "技能", "用户", "一个", "进行", "可以", "这个", "以及", "把", "将", "对", "从",
+])
+
+/**
+ * 描述里真正用来路由的词。丢掉套话（use this skill when…）和过短的英文词。
+ * 中文没有空格，用相邻二字作为特征，避免整句变成一个 token。
+ */
+export function distinctiveTokenSet(text) {
+  const set = new Set()
+  const str = String(text ?? "").toLowerCase()
+  let prevCjk = ""
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i)
+    if (isCjkUnit(code)) {
+      const ch = str[i]
+      if (prevCjk && !STOPWORDS.has(prevCjk) && !STOPWORDS.has(ch)) set.add(prevCjk + ch)
+      prevCjk = STOPWORDS.has(ch) ? "" : ch
+      continue
+    }
+    prevCjk = ""
+    if (!isAsciiWord(code)) continue
+    let j = i
+    while (j < str.length && isAsciiWord(str.charCodeAt(j))) j++
+    const word = str.slice(i, j)
+    if (word.length >= 3 && !STOPWORDS.has(word)) set.add(word)
+    i = j - 1
+  }
+  return set
+}
+
+/**
+ * 一条会被展示给模型的 skill，每步付出的描述 token。
+ * 扫描时已经算过的 `stepTokens` 直接复用；description 被改写（例如精简预览）时重算。
+ */
+export function advertisedStepTokens(skill, description = skill?.description ?? "") {
+  if (skill && description === skill.description && Number.isFinite(skill.stepTokens)) return skill.stepTokens
+  return estimateTokens(`${skill?.id ?? ""} ${skill?.displayName ?? ""} ${description}`)
 }
 
 /** 终端显示宽度（CJK 记 2 列） */

package/src/plan.mjs

@@ -1,38 +1,64 @@
-import { estimateTokens } from "./parse.mjs"
+import { advertisedStepTokens, distinctiveTokenSet } from "./parse.mjs"
 import { resolveWinners } from "./lint.mjs"
 
 export const DEFAULT_DESC_TARGET = 160
 export const DEFAULT_STEPS = 100
 
 function costOf(skill, description = skill.description) {
-  return estimateTokens(`${skill.id} ${skill.displayName} ${description}`)
+  return advertisedStepTokens(skill, description)
+}
+
+function firstSentenceEnd(value) {
+  const match = /[.!?。！？]/.exec(value)
+  return match ? match.index + 1 : -1
 }
 
 /**
- * 把 description 截到目标长度，优先在句子边界断开（中英文标点都算）。
- * 纯函数：相同输入永远得到相同输出，便于在报告里预览「如果这么改会省多少」。
+ * 目录里只需要路由用的第一句。第一句放得进上限就只留它；
+ * 第一句本身超长时，再在分句标点处断开，最后才按字符硬切。
+ * 纯函数：相同输入永远得到相同输出。
  */
 export function trimDescription(text, limit = DEFAULT_DESC_TARGET) {
-  const value = String(text ?? "")
+  const value = String(text ?? "").trim()
   if (value.length <= limit) return value
+  const sentenceEnd = firstSentenceEnd(value)
+  if (sentenceEnd > 0 && sentenceEnd <= limit) return value.slice(0, sentenceEnd).trim()
   const slice = value.slice(0, limit)
   const cut = Math.max(
-    slice.lastIndexOf("。"),
-    slice.lastIndexOf("."),
-    slice.lastIndexOf("！"),
-    slice.lastIndexOf("？"),
+    slice.lastIndexOf("，"),
+    slice.lastIndexOf(","),
     slice.lastIndexOf("；"),
     slice.lastIndexOf(";"),
+    slice.lastIndexOf("、"),
     slice.lastIndexOf("\n"),
   )
-  const trimmed = cut >= limit * 0.5 ? value.slice(0, cut + 1).trim() : slice.trim()
+  const trimmed = cut >= limit * 0.5 ? value.slice(0, cut).trim() : slice.trim()
   return trimmed || slice.trim()
 }
 
-/** 在候选中选「数量最少」的一组，使节省量 ≥ gap；按单项节省降序取前缀即为最优。 */
-function pickMinimal(items, gap) {
+/** 这条描述有多少已经被别的 skill 说过。1 = 触发词是别人的子集，0 = 完全独特。 */
+function redundancyOf(id, sets) {
+  const mine = sets.get(id)
+  if (!mine || mine.size < 3) return 0.35
+  let best = 0
+  for (const [other, tokens] of sets) {
+    if (other === id || !tokens?.size) continue
+    let shared = 0
+    for (const token of mine) if (tokens.has(token)) shared++
+    const covered = shared / mine.size
+    if (covered > best) best = covered
+  }
+  return best
+}
+
+/**
+ * 选一组隐藏项盖住缺口。排序不是「谁最贵藏谁」，而是节省 × 重复度：
+ * 触发词已经被别的 skill 覆盖的，优先藏；独特的留到最后。
+ */
+function pickPreserving(items, gap) {
   if (gap <= 0) return { count: 0, savings: 0, items: [], enough: true }
-  const sorted = [...items].sort((a, b) => b.tokens - a.tokens || a.id.localeCompare(b.id))
+  const score = (item) => item.tokens * (0.15 + 0.85 * item.redundancy)
+  const sorted = [...items].sort((a, b) => score(b) - score(a) || a.id.localeCompare(b.id))
   const picked = []
   let savings = 0
   for (const item of sorted) {
@@ -49,8 +75,8 @@ function pickMinimal(items, gap) {
  * 规则：
  * - 只有会被「展示给模型」的定义才有成本；被遮蔽的重复定义省不出 token（诚实很重要）。
  * - 精简 description 不改变可发现性；隐藏（autoinvoke: false）省掉整条成本，但仍可用 @id 加载。
- * - 推荐方案先精简所有超长描述，再按「单项节省最大」贪心隐藏，直到进入预算。
- *   被隐藏的技能若也被精简过，其节省按原始成本计，不会重复计算。
+ * - 推荐方案先把超长描述收成第一句，再优先隐藏「触发词已经被别的 skill 覆盖」的条目。
+ *   被隐藏的技能若也被精简过，其节省按精简后的成本计，不会把同一份 token 算两次。
  */
 export function planBudget(
   audit,
@@ -86,23 +112,27 @@ export function planBudget(
   trims.sort((a, b) => b.saving - a.saving || a.id.localeCompare(b.id))
   const trimSavings = trims.reduce((sum, item) => sum + item.saving, 0)
 
-  // 2) 只隐藏（不精简）的方案
+  const tokenSets = new Map(advertised.map((skill) => [skill.id, distinctiveTokenSet(skill.description)]))
+
+  // 2) 只隐藏（不精简）的方案。重复的先藏。
   const hideCandidates = advertised.map((skill) => ({
     id: skill.id,
     file: skill.file,
     tokens: costOf(skill),
+    redundancy: redundancyOf(skill.id, tokenSets),
   }))
-  const hideOnly = pickMinimal(hideCandidates, gap)
+  const hideOnly = pickPreserving(hideCandidates, gap)
 
-  // 3) 推荐方案：先精简，再在「精简后的成本」上隐藏
+  // 3) 推荐方案：先精简，再在「精简后的成本」上按重复度隐藏
   const afterTrim = advertised.map((skill) => ({
     id: skill.id,
     file: skill.file,
     tokens: trimMap.get(skill.id)?.cost ?? costOf(skill),
     originalTokens: costOf(skill),
+    redundancy: redundancyOf(skill.id, tokenSets),
   }))
   const postTrimTotal = afterTrim.reduce((sum, item) => sum + item.tokens, 0)
-  const recommendedHides = pickMinimal(afterTrim, Math.max(0, postTrimTotal - target))
+  const recommendedHides = pickPreserving(afterTrim, Math.max(0, postTrimTotal - target))
   const hideSavings = recommendedHides.savings
   const savings = trimSavings + hideSavings
   const final = Math.max(0, current - savings)