@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/attribution-verification.md

@@ -0,0 +1,69 @@
+# Attribution Verification
+
+Author-method / project-method pairings drafted from training-data recollection have a high error rate. The SKILL.md entrypoint states the rule and the hard triggers; this file is the operational mechanism: the failure shapes you are watching for, the implicit-attribution surfaces that bypass naive checks, the source-quality bar, and the pending-row workflow when verification cannot complete in this commit.
+
+## Why This Rule Exists
+
+Claims of the form "X is known for Y", "Y was originated by X", "X 提出 Y", "X cheatsheet / heuristic / method", or any other author-method / project-method pairing have a high error rate when drafted from training-data recollection. Independent review (codex / external fact-check) catches this class routinely. The rule below removes the need for adversarial review to find these one by one.
+
+## Common Failure Shapes
+
+- **Famous-adjacent attribution**: attributing a method to the most famous adjacent author rather than the actual originator — e.g., attributing a method to a popular practitioner when the meeting / origin was a different person years earlier.
+- **Wrong standard part number**: citing a standard's part / year / clause number incorrectly. The standard exists; the citation does not.
+- **Heuristic conflation**: conflating an author's well-known heuristic with unrelated folklore in the same field. Both sources exist; the pairing is invented.
+
+## Attribution-Required Test
+
+### Hard Triggers (Always Required)
+
+Attribution is REQUIRED whenever the claim names any of:
+
+- **Origin** — who first proposed / wrote / invented X
+- **Chronology** — when X was first proposed / published / standardized
+- **Standard version** — RFC / ISO / IEEE / PEP part / year / clause numbers
+- **Authority** — "X is the recommended way to do Y per <named authority>"
+- **Named methodology lineage** — X is a variant / derivative / successor of Y
+
+### Secondary Heuristic (Load-Bearing Test)
+
+Apply this ONLY when no hard trigger fires. If removing the named source materially weakens the rule's force, attribution was load-bearing and is still required.
+
+### Generic-Framing Carve-Out
+
+"Generic framing" ("业内常用" / "industry practice" / "commonly recommended") is acceptable ONLY when the executable guidance stands without any authority claim. If the rule needs a name to be believed, you cannot generic-frame it.
+
+## Implicit Attribution Counts
+
+Agents cannot bypass the rule by moving the claim to a header or bibliography line. All of the following count as attribution claims and need the same verification:
+
+- Section placement (a rule under a heading named after an author / framework)
+- Header naming (`## The Smith Method`)
+- "based on X-style literature" phrasing
+- Juxtaposition implying origin (rule followed by a name with no separator)
+- `see also: X, Y` suffix lists
+- Block quotes without captions
+- Reference-file links pointing to a single author's work
+
+If any of these surfaces names a source, the source must satisfy the source-quality bar below.
+
+## Source-Quality Bar
+
+"Verifiable" means one of:
+
+- **Primary source** — official standard / catalog page with correct part / year, original paper / book, publisher page, stable canonical docs.
+- **Authoritative secondary source** — an organization or publication recognized as authoritative in the field, citing the primary.
+- **OR at least two independent sources that do not cite or copy each other**. Aggregator pages and wikis do NOT count as independent unless they are themselves backed by primary citations.
+
+A single blog post does not satisfy the bar regardless of how well-known the blogger is.
+
+## Pending Blocks Landing
+
+Unverified author-method pairings are recorded as `attribution pending` and tracked in the target-output / provenance-to-target rows. Per the standard pending-row semantics, any pending row blocks a complete / final claim.
+
+Three resolution paths:
+
+1. **Complete the verification** — find the primary / 2-independent source, add it as a footnote / inline citation, mark the row landed.
+2. **Downgrade the claim** — remove the authority, restate the rule as generic guidance that stands on its own merits, drop the attribution row.
+3. **Finalize as `interim`** — keep the attribution unverified, mark the commit interim, queue the verification for a follow-up commit.
+
+Memory-grade attribution is not evidence. A claim landed on the assumption "I'm pretty sure X said this" without a citation is the failure mode this rule prevents.

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/bootstrap-slim-c3-obligation-table.md

@@ -0,0 +1,112 @@
+# bootstrap.md C-3 最终义务表
+
+本表是 MR !505 的可复查 semantic-control 证据。比较基线为 MR !505 的 merge-base；最终 `bootstrap.md`
+为 18262B（基线 18664B，减少 402B / 2.2%）。
+
+## 行集与分类
+
+对基线文件和最终文件运行
+`skills/skill-extraction-workflow/scripts/governing-chain-diff.py BEFORE_FILE bootstrap.md`
+得到 25 行；另保留工具长度阈值未覆盖的 R34，共 26 行。
+
+- `merged`：bootstrap 保留完整 carrier；canonical 重复不改变分类。
+- `subsumed`：bootstrap 删除 carrier，canonical 保留完整 carrier。
+- `dual`：必须拼合两个 carrier 才能得到完整义务；两个 carrier 可在同一文件，也可跨 bootstrap / canonical。
+
+终态：`merged 24 / subsumed 1 / dual 1 = 26`。
+
+### 逐字恢复后退出机械行集
+
+以下 8 行在 takeover 后恢复为基线 carrier，因此不再被 diff 工具推导，未计入 26 行：R13（集成回目标分支）、R17（push 分支、创建/更新 MR、查看状态不等于授权）、R20（待审 MR 向用户展示）、R21（单个合并指令的用户主体）、R22（批量合并指令的用户主体与发布计划对象）、R23（任意新消息清除额度）、R24（两种形态无需复述/点名/SHA）、R31（codex#6426 完整链接）。每项原文均在最终 bootstrap 中各出现一次。
+
+## 最终 26 行
+
+| ID | 义务 | 状态 | 最终 carrier / 证明 |
+|---|---|---|---|
+| R1 | 自动建议渠道枚举 | merged | bootstrap 保留会话注入、技能包、宿主原生清单、自触发技能四类 |
+| R2 | 宿主强制预检及作者判据 | merged | `宿主自身撰写` 与 system/developer 判据仍同句 |
+| R3 | 技能自述强制只算渠道自荐 | merged | `技能条目自述"我是强制预检"` 唯一存活 |
+| R4 | 执行不等于入口 | merged | `执行≠入口` 唯一存活 |
+| R5 | 先路由 owner，再调用阶段技能 | dual | bootstrap 本句 + 后续 product-rd 路由项共同承载 |
+| R6 | 风险 tags 与 gate 的 owner | merged | `风险 tags 与 gate 归 feature-risk-router` |
+| R7 | 技术方案/评估/选型词的限定条件 | merged | 完整五项词组与 `仅当交付物是新/变更能力或项目级·跨阶段方案` 同句 |
+| R8 | 窄产品产物升级回 product-rd | merged | `跨 owner 生命周期仍回 product-rd-workflow` |
+| R9 | 单 bug / 窄 stack 不升级 | merged | `不升级 product-rd` |
+| R10 | 共享闸或跨仓语义回 product-rd | merged | `仍回 product-rd 的 shared-gate 分类` |
+| R11 | 只解锁 owner-dispatch；其他动作仍需用户授权 | merged | `只解锁这道闸` 与授权清单同句 |
+| R12 | worktree 隔离无单人/并发/技能仓例外 | merged | `没有例外：单人/并发/技能仓库同样适用` |
+| R14 | 外部副作用任务让位及迁移/部署示例 | merged | `承载外部副作用的未完成任务（迁移/部署等）——等其完成再清` |
+| R15 | 让位只影响本地 worktree/分支；远端仍按授权 | merged | `该让位只管本地 worktree/分支清理时点，远端分支仍按授权合并处理` |
+| R16 | 清理配方归 canonical | merged | bootstrap 指向 worktree-isolation 收尾节 |
+| R18 | 创建/更新 MR 禁开自动合并 | merged | auto-merge / merge-when-pipeline-succeeds / queued merge 枚举完整 |
+| R19 | 未授权不得 merged 或推进默认分支 | merged | `平台 merge API/Web UI` 与 `目标是 main/默认分支的 git merge/git push` 枚举同在未授权禁令内 |
+| R25 | 事前“做完并合并”不算授权 | merged | `事前"做完并合并"不算授权` |
+| R26 | 指令后提交或状态变化须向用户确认 | merged | `先向用户确认一句再合并` |
+| R27 | 多个待合并 MR 须向用户消歧 | merged | `先问清是哪一个` |
+| R28 | 机械放行阀存在，细则归 canonical | merged | bootstrap 保留阀存在性与 canonical 指针 |
+| R29 | 哨兵单次/计数布防机制 | subsumed | `skills/worktree-isolation/SKILL.md` 的 `UserPromptSubmit 哨兵在用户**单独回复**` 唯一完整 carrier；bootstrap 不复制布防细节 |
+| R30 | 直推 main / auto-merge 永不放行及 canonical 指针 | merged | bootstrap 同时保留永不放行绝对句与 `以该节为准` |
+| R32 | 自审收敛后再交独立评审 | merged | `可证明的实现者自检` 与 `预期通过再交评审` |
+| R33 | 自审覆盖分支/路径/状态与四个风险轴 | merged | security/privacy/authority/数据丢失轴完整 |
+| R34 | invoke 闸枚举引导语的误计数修正 | merged | `硬判据：` 后仍有 ①②③④ 四项 |
+
+## 阈值盲区复核
+
+默认 `min_chars=25`，含 CJK 文本的有效 floor 为 16。对基线和终态额外以
+`min_chars=1` 解析，再从低阈值变化中扣除默认行集，原始结果为：
+
+```console
+$ python3 -c 'import importlib.util,subprocess,sys; p="skills/skill-extraction-workflow/scripts/governing-chain-diff.py"; s=importlib.util.spec_from_file_location("gcd",p); m=importlib.util.module_from_spec(s); sys.modules[s.name]=m; s.loader.exec_module(m); b=subprocess.check_output(["git","show","69d16032:bootstrap.md"],text=True); a=subprocess.check_output(["git","cat-file","blob","ec0ba4fd3fe4"],text=True); ch=lambda n:{(o.key,o.chain) for o in m.parse(b,min_chars=n) if (o.key,o.chain) not in {(x.key,x.chain) for x in m.parse(a,min_chars=n)}}; low=ch(1); default=ch(25); x=sorted(low-default); print(f"low_changed_removed {len(low)}"); print(f"default_changed_removed {len(default)}"); print(f"subthreshold_changed_removed {len(x)}"); [print(f"effective_len={m.effective_len(k)} text={k}") for k,_ in x]'
+low_changed_removed 26
+default_changed_removed 25
+subthreshold_changed_removed 1
+effective_len=11 text=三条硬判据：
+```
+
+同一结果的紧凑记录为：
+
+```text
+low_changed_removed 26
+default_changed_removed 25
+subthreshold_changed_removed 1
+effective_len=11 text=三条硬判据：
+```
+
+因此 R34 是默认 floor 唯一发生 changed/removed 的基线义务；本结论只证明基线义务保全，
+不声称枚举终态新增的低阈值文本。
+
+## 可复跑机器证据
+
+权威是下列命令对当前文件的实时结果，不是本表或 source-register 的声明：
+
+```console
+$ git diff --quiet -- bootstrap.md skills/skill-extraction-workflow/references/source-register.md skills/skill-extraction-workflow/references/bootstrap-slim-c3-obligation-table.md; echo $?
+0
+$ git rev-parse --short=12 :bootstrap.md
+ec0ba4fd3fe4
+$ test "$(git rev-parse :bootstrap.md)" = "$(git rev-parse ec0ba4fd3fe4)"; echo $?
+0
+$ git cat-file blob ec0ba4fd3fe4 | wc -c
+   18262
+$ git cat-file blob ec0ba4fd3fe4 | rg -o -F 'UserPromptSubmit 哨兵' | wc -l
+       0
+$ rg -o -F 'UserPromptSubmit 哨兵' skills/worktree-isolation/SKILL.md | wc -l
+       1
+$ git cat-file blob ec0ba4fd3fe4 | python3 skills/skill-extraction-workflow/scripts/governing-chain-diff.py <(git show 69d16032:bootstrap.md) /dev/stdin
+governing-chain-diff: /dev/stdin
+derived row set: 25
+$ ruby skills/skill-extraction-workflow/scripts/register-firing-path-resolution.rb .
+register_firing_path_resolution_ok (237 locators resolved)
+```
+
+`69d16032` 是本 MR 已记录且唯一解析的 merge-base；`ec0ba4fd3fe4` 是候选 `bootstrap.md`
+的 blob 身份，短 ref 若将来产生歧义会由 Git 报错，而不会静默换成别的内容。首条
+`git diff --quiet` 证明 review 时 resolver 所读的三份工作树文件与 index 相同；提交后 blob
+只有在候选不再改写并确实进入 landing commit 时才随 commit 保留。landing 后必须运行
+`test "$(git rev-parse HEAD:bootstrap.md)" = "$(git rev-parse ec0ba4fd3fe4)"`；非零即说明评审后
+内容漂移，不得沿用本表结论。该 commit-state 等值检查在 commit 产生前不能伪报执行。
+两条固定串计数分别证明 R29 的 bootstrap carrier 为 0、canonical carrier 为 1。
+
+- **Landing 后必须验证候选 blob**：提交后必须执行上述 `HEAD:bootstrap.md` 等值检查；非零时必须阻断交付并重新冻结候选证据。
+`governing-chain-diff.py` 返回 1 表示行集非空，是本次预期结果。历史提交的 17998B / 31 行
+快照不作为终态证据。

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/coverage-exhaustion-traps.md

@@ -0,0 +1,45 @@
+# Coverage-exhaustion traps — worked failure shapes
+
+Companion to the **`digest-masks-corpus trap`** Core Rule in `SKILL.md` (under *Evidence, RCA, charter & attribution*). That Core Rule carries the **gates + triggers** (when an "exhausted / complete / no-gap / fully-extracted" claim is unsupported, and what closes it). This file carries two things: the **relocated gate detail for variants (a0) and (4)** — the executable obligation text moved here from the Core Rule so the entrypoint stays at gate altitude (the Core Rule keeps the variant names and a pointer) — and the **recurrence-memory** for the core form and variants (a)/(b)/(c): the concrete historical failure shapes that justify each gate, plus the fuller worked examples. Read it when you are about to make such a claim and want the concrete shape of how each variant goes wrong, or when you need the (a0)/(4) obligation text.
+
+The trap has one core form and variants (a)/(b)/(c) as failure shapes; the Core Rule's walked enumeration adds (a0) and standing gate (4) to the same fix family, and this file carries their relocated gate detail. The core form and variants (a)/(b) share one fix — **enumerate the real underlying artifact and mark each unit `read`/`skipped`, rather than trusting the digest**. Variant (c) is the case where *no artifact masked anything*: the **source-class universe itself was never enumerated**, so its fix is to enumerate the class taxonomy instead.
+
+## Core — digest exhaustion ≠ repo exhaustion
+
+The digest (a high-quality maintainer `AGENTS.md`/`CLAUDE.md`, README, CONTRIBUTING, or architecture/design doc) and the underlying code are distinct source classes; a strong digest masks how much code went unread.
+
+**Failure shape:** deep-read a 50KB `AGENTS.md`, land its lessons, write "extraction exhausted" while ~hundreds of KLOC are unread, and a user has to ask "你没看代码么 / did you read the code".
+
+Note on depth: the code-corpus sweep is usually inventory + owner-mapping + novelty-spot depth, not line-by-line — but it must be a **closed register row**, and is commonly low-yield because the digest already distilled the reusable layer. Record that outcome honestly rather than skipping the row.
+
+## Variant (a) — self-retrospective form (the digest is your OWN output)
+
+In a task / session / multi-batch retrospective the same trap fires with the agent's own artifacts as the digest: prior retro summaries, MR / commit *descriptions*, and project-memory notes *about* the work are a lossy digest of the actual change set, not the change set. Reading your own summaries back and finding nothing new is NOT evidence the diffs hold nothing — and a fact recorded only at the project-memory layer is not the same as a lesson promoted to the owning shared skill.
+
+**Failure shape:** declare a multi-repo program "fully summarized" from MR descriptions and self-notes while the real diffs still carry reusable lessons (a locale-stable manifest-sort fix, a per-surface-redaction refinement) that were noted at the project layer but never promoted, and a user has to ask "根据实际变更核查 / 不要只看 comment".
+
+## Variant (b) — benchmark / no-gap form (the conclusion is "we already cover this")
+
+When the source is an external artifact you are benchmarking to decide whether WE must extract, a "no gap / already covered / it converges with what we already have" conclusion is ALSO a coverage claim under this trap. The digest here is the source's **overview / README / feature-docs / commit-messages — prose written to *advertise* a feature** — which systematically omits the very safety mechanics worth borrowing. Concluding "no new lesson" requires reading the source's **load-bearing decision surface**: the actual decision rules, the claim-vs-ground-truth checks, the data-loss guards. Where that surface is code separate from the docs, read the code; where the load-bearing artifact is *itself* executable prose (a skill's own `SKILL.md`, a standards/spec doc with no code), read THAT rule surface in full — not the overview of it — and scope the no-gap claim to the artifact actually read.
+
+**Benchmark source classes include agent-native product repositories, not only skill packs.** When the benchmark target is "how does the outside world do this", enumerate at least: published skill/prompt packs (`superpowers`, `gstack`, vendor packs); *and* product repositories developed largely by agents that ship their development discipline in the tree (root/subtree `AGENTS.md`, agent decision-record and note conventions, repo-local skills, testing policy, pre-push/evidence-selection rules, postmortem and defensive-pattern docs). The second class is where operating discipline lives; a benchmark that only reads skill packs mistakes the absence of a competing skill for the absence of practice. Read such a repository's discipline layer as its own register row (digest `AGENTS.md`/README first, then the notes/skills/policy corpus — the digest-masks-corpus rule applies twice over), classify its portfolio stability before borrowing, and land what you borrow as "one industry shape" unless independently confirmed.
+
+**Failure shape:** "this external self-maintenance design is already covered, nothing to extract" claimed twice from its feature-docs + commit messages, until a user said "真实看对方实现逻辑 / read the actual implementation" and the code revealed two real gaps (a claim-vs-ground-truth reconciliation and a package-integrity guard) the docs never surfaced.
+
+## Variant (c) — channel-taxonomy form (nothing masked it; the class set was never listed)
+
+The three shapes above all have a **digest standing in front of a corpus you could already reach**. This variant has no digest and no corpus-in-hand: the claim is that an *acquisition channel set* is exhausted, and it fails because the **taxonomy of channel classes was never enumerated** — so the agent kept searching harder *inside* the two or three classes it had thought of. The tell that separates it from the core form: each round surfaces a **class the agent had never considered**, not another artifact within a known class.
+
+Its fix is therefore not "read the real artifact" but **walk a seed list of channel classes to catch the ones never considered, and then scope the claim to what was actually walked** — the seed list is not a universe, so it licenses no exhaustion claim; what makes the output falsifiable is recording each class's search boundary and which classes were not walked, because otherwise "I could not find more" and "there is no more" are indistinguishable. Closure and downgrade belong to the owning skill's existing coverage gate, not to a status vocabulary invented here.
+
+**Failure shape:** an agent researching one organization from public sources declares "the public channels are mined out" five separate times; each time the user pushes back, a **previously unconsidered channel class** lands major evidence (an archive route around a bot-block, a regulator's bulk dataset, a mandatory-disclosure regime, another jurisdiction's statutory filings, a filing the organization voluntarily publishes on its own site). No artifact was hiding these — they were never on a list. The domain-side channel taxonomy lives with the research owner (`skills/multi-perspective-research/references/public-disclosure-channels.md`, repo-root relative); what belongs here is the recurrence memory that an exhaustion claim over a *channel set* needs a walked class list, not more effort inside the known classes.
+
+## Variant (a0) — produced-artifact + next-run-delta (relocated gate detail)
+
+**Firing point: for a task/session retrospective, this variant fires at CHARTER time — the produced-artifact row (i) enters the charter's evidence plan as its FIRST source class (see the Evidence plan field in `source-to-skill-extraction.md`), while the next-run-delta row (ii) is a separate required charter/closeout record, not a source class — not only when an exhausted/complete claim is about to be made** (the original anchor, kept as backstop). Observed failure shape of the late anchor: a 7-session program retro that never claimed "exhausted" walked past this gate entirely, took only correction turns as evidence, and landed zero method/craft lessons while r-series reports and a benchmark corpus sat unread in the project.
+
+When the source is a task/session that PRODUCED runnable artifacts (scripts, commands, queries, configs, fixtures), two rows are required and neither substitutes for the other: **(i)** the produced artifacts are enumerated as their own source class in the **source register** (existing status vocabulary — `read`/`deep-read`/`excluded`/`routed`, with "project-specific only" recorded as the *reason* on an `excluded` row, never as a new status), and each reusable technique found in them gets a row in the **provenance-to-target diff** under its existing vocabulary (`landed`/`routed`/`downgraded`/`pending`) — **attaching the artifacts to a deliverable, or archiving them in the project, is NOT `landed`**, because a bundle hanging off one document is unreachable from the next project; and **(ii)** a **next-run delta** row in the source register whose fields are: what this run's cost was actually spent on, what the next run of this task shape must do IN WHAT ORDER, and which prerequisites must hold regardless of order — a sequencing lesson is a counterfactual about ordering, not an artifact, so the per-artifact sweep structurally cannot surface it. The framing trap this closes: extraction defaults to asking "what rules did we learn" (declarative) and never asks "what would we do differently, in what order" (procedural), so a session whose most reusable assets were working code and a better sequence lands only prose rules and passes every gate.
+
+## Gate (4) — the per-item verdict-disposition obligation (relocated gate detail)
+
+The verdict owes a **per-item disposition row EVEN WHEN THE ROUND LANDS NOTHING** (no commit fires to catch an advertising-level verdict): each row records the load-bearing surface actually read (section/line/rule — NOT headers/`When to invoke` blurb/feature-list), the owning organization artifact (`file:rule`) OR `route-to-tool` / `out-of-scope: <reason>`, and for `covered` the mechanical firing path. A `quick`/`light`/`sweep`/`triage` framing does **NOT** waive the load-bearing read. Record the row on a **concrete surface** — the triage turn's final response OR persistent scratch / `source-register`, never chat-ephemeral. (Honesty: absent a host/review hook checking that surface, this stays recognition-dependent — salience, not mechanical enforcement.) A repeated user "深度分析了么 / did you deep-read" across rounds is the recurrence signal that an advertising-level verdict shipped; treat it as a validation-gate defect.

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/description-authoring.md

@@ -0,0 +1,162 @@
+# Description Authoring For Auto-Triggering Skills
+
+Use this when writing or rewriting the YAML frontmatter `description` of a skill that AI clients (Claude Code, Codex, opencode, Gemini CLI, and others) match against user requests to decide which skill to auto-invoke. A skill's `description` is its routing surface — it is executable, not documentation. Get this wrong and the skill never fires, or fires for the wrong asks.
+
+## When this reference applies
+
+- Routing / workflow / cross-cutting skills (e.g. `product-rd-workflow`, `feature-risk-router`, `defect-diagnosis`, `testing-strategy`, `skill-extraction-workflow`, `tighten-doc`, `multi-agent-delegation`, `product-ui-ux-design`).
+- Any skill where the same user can phrase the trigger many different ways and the skill must catch most of them.
+
+When this reference does NOT apply:
+
+- Stack-specific implementation skills (`web-react-dev`, `go-microservice-dev`, etc.) where the trigger is usually an explicit technology mention. They benefit from some of these rules but the multi-language utterance discipline below is overkill.
+- Skills that are only invoked by explicit slash command and never need to auto-trigger.
+
+## The 4-section structure
+
+Block-scalar YAML, ordered:
+
+```yaml
+description: |
+  <One-line capability statement: what this skill does, what it owns, what it routes out. Product-agnostic; no business nouns.>
+
+  Use when asked to "<CN trigger 1>", "<CN trigger 2>", ..., "<EN trigger 1>", "<EN trigger 2>", ...
+
+  Proactively invoke when <indirect signal A>, <indirect signal B>, ... — even when the literal skill name is absent. Do not invoke just because <common over-fire situation>.
+
+  Skip when <already-scoped-to-other-skill situation> (e.g. "<example phrase>" → <other-skill>; "<example phrase>" → <other-skill>).
+```
+
+Four sections. In order. Each does a different job:
+
+### Section 1 — Capability one-liner
+
+- One sentence. Names what the skill OWNS and what it ROUTES OUT.
+- Product-agnostic phrasing. Do not import business nouns, project paths, repo names, or tool-specific habits from source projects.
+- Do NOT stuff a long list of related implementation skill names here — that dilutes keyword density for matching. Implementation routing belongs in the skill body, not the description.
+- **Prompt-engineering discipline for the description text itself**: a `description` is a prompt that selects the skill, so write it simple and direct; reach for few-shot phrasings only when the trigger has genuinely confusing edge cases that one-liners cannot disambiguate. Do NOT bake explicit chain-of-thought directives ("think step by step", "reason carefully then …") into the description — for reasoning-capable models they are usually unnecessary and can degrade behavior (OpenAI reasoning guidance); for Claude, prefer general instructions over prescriptive step lists (Anthropic prompting guidance). If a non-reasoning model genuinely needs stepwise scaffolding for a specific task, put that in the task prompt or examples that the skill triggers, not in the description itself — the description's job is to trigger and route, not to dictate cognition.
+
+Good: `End-to-end product R&D workflow: shapes requirements and routes design / architecture / dev / test / review / release / postmortem stages to the right skill.`
+
+Bad: `Use when turning a product idea, feature request, bug, refactor, or release goal into an end-to-end product R&D workflow. Coordinates product clarification, architecture decisions, design readiness routing, implementation skills such as app-cross-platform-dev, web-react-dev, go-microservice-architecture/go-microservice-dev, and python-service-architecture/python-service-dev, testing, code review, release readiness, and postmortem learning.`
+(Too long; implementation skill names are noise for trigger matching.)
+
+### Section 2 — `Use when asked to "<quoted phrases>"`
+
+- Quoted, comma-separated. Real utterances people say. Not abstract capability descriptions.
+- Include both Chinese AND English variants if either language could realistically appear. Do not assume English-only or Chinese-only.
+- Order: CN phrases first (or whichever language is more common for the team), then EN. Mixing is acceptable; consistency within a skill matters less than coverage.
+- Each phrase should pass the 80% precision threshold (see below). Phrases that don't, must either be dropped or anchored with disambiguating context.
+
+### Section 3 — Proactively invoke when
+
+- Covers indirect signals: user described a situation that the skill owns but did not say the skill's name or any of the quoted triggers.
+- Be specific about the situation; vague proactive clauses fire constantly.
+- Add a "do not invoke when ..." negative clause for the most likely over-fire case. This is in-section guidance, not a separate Skip-when (Skip-when is about already-named-other-skill, not about ambiguous proactive).
+
+Good: `Proactively invoke when the user pastes a stack trace, error message, failed CI output, alert, or describes unexpected behavior — even when they did not ask for "debugging" explicitly. Run before any fix is proposed.`
+
+Bad: `Proactively invoke when the user shares a draft doc / spec / plan and asks for opinion or review.`
+(Too broad — competes with every review-type skill on the same phrasing.)
+
+### Section 4 — Skip when
+
+- Covers situations where another skill clearly owns the ask, with `→ skill-name` pointers.
+- Examples use real user phrasings, not abstract criteria.
+- This is a divert, not a trigger. The phrases here should NOT appear in the Use-when list — those are mutually exclusive jobs.
+- Use this to resolve known collisions with sibling skills.
+
+Good: `Skip when the ask is already scoped to one stack (e.g. "fix this React render bug" → web-react-dev; "add a GORM index" → go-microservice-dev; "调下这个按钮间距" → product-ui-ux-design), or when the user is reporting a defect / failure / regression → defect-diagnosis owns reproduction and root cause first.`
+
+## Precedence against session-injected process skills
+
+A routing / workflow skill competes not only with sibling skills but also with process-discipline skills that some hosts INJECT at session start with very forceful language (e.g. a brainstorming skill whose description says "MUST use before creating features / adding functionality"). At initial routing time the router primarily sees skill names, descriptions, and host/session rules — the workflow body has not loaded yet, so an "Entry precedence" paragraph in the body does NOT win the routing decision. If your routing skill should own the entry point for a request class that an injected process skill also claims, the description must:
+
+- Carry the high-frequency delivery utterances in the languages users actually type for this skill (include CN + EN only when both are real high-frequency forms), phrased the way they phrase them ("加个功能", "实现/接入某能力", "add a feature"). Each phrase must still pass the 80% precision threshold (above) — anchor a broad delivery phrase to the owned request class rather than dropping it in bare. An injected skill that literally matches "adding functionality" otherwise wins on the unanchored generic phrase.
+- State scoped entry ownership for this request class, and describe the process skill as an internal step ONLY when that is actually true under the host's rules — do not teach a blanket priority claim over an injected skill the host may still require. Scope it ("for feature/requirement delivery") so it does not over-claim against pure process-only asks (e.g. retro → skill-extraction-workflow).
+
+For teammates using the shared skill on description-based routing hosts, this is a zero-config fix: it ships in the description and avoids per-project memory or CLAUDE.md overrides. Validate it like any routing-surface change (dual-track challenge below).
+
+## Trigger phrase quality: the 80% precision threshold
+
+A quoted trigger phrase should belong to its skill in at least 80% of real-use contexts. If a phrase would commonly mean something else, it must be DROPPED or ANCHORED.
+
+### Drop (too generic, no rescue possible)
+
+- `"改下样式"` — almost always means "change CSS now", which is implementation, not design ownership. Drop.
+- `"怎么验证"` — covers release verification / smoke checks / deploy status / test planning — too broad. Drop.
+- `"梳理一下"` — could be requirements, architecture, code, or doc — too broad. Drop.
+- `"重写下"` — in code-review context, this means rewrite the code, not the doc. Drop.
+- `"感觉怎么样"` — open evaluative question for any artifact. Drop.
+- `"批量处理这批任务"` / `"parallelize this"` — can mean shell batching, code concurrency, data-pipeline parallelism — not necessarily agent dispatch. Drop.
+- `"bug report"` — collides directly with bug-diagnosis territory; do not put in product-workflow proactive. Drop or move to Skip-when as a route pointer.
+
+### Anchor (add disambiguating context)
+
+When the bare phrase is too generic but a slightly longer version is clearly in-scope:
+
+- `"重写下"` → `"重写下这个文档"` (anchored to docs)
+- `"错误提示怎么写"` → `"用户看到的错误提示怎么写"` (anchored to user-facing surface, not API/CLI/log)
+- `"怎么验证"` → `"测试层面怎么验证"` (anchored to test-layer planning)
+
+The anchor must shift the surface meaning, not just add a noun.
+
+### Keep (already specific enough)
+
+Phrases that are tightly bound to one skill's territory:
+
+- `"这个 bug 怎么修"`, `"为什么挂了"`, `"昨天还好好的"` — clearly defect-diagnosis.
+- `"复盘"`, `"沉淀经验"`, `"总结经验教训"` — clearly skill-extraction-workflow.
+- `"这个页面怎么设计"`, `"设计走查"`, `"设计验收"` — clearly product-ui-ux-design.
+- `"立项"`, `"新项目怎么搞"`, `"让我们做一个 X"` — clearly product-rd-workflow.
+
+## Length discipline: 800-char cap
+
+The repo validator enforces an 800-character maximum on `description` (parsed as YAML): `check-ccl-skills.sh` fails with `description_too_long_for_opencode` above 800 chars and warns with `description_long_for_opencode` above 600, because longer descriptions dilute the trigger signal and can be truncated in host skill listings. If either threshold changes, update this section in the same diff — this file is the pre-edit reading for description authors and must not drift from the executor again. Practical tips when you exceed:
+
+- Move route-pointers from the Proactively-invoke clause INTO Skip-when. Skip-when's job is to list "go elsewhere" targets, so route pointers fit naturally there and save proactive-clause room.
+- Drop redundant proactive triggers (e.g. "right before a doc lands in a shared workspace" was vague and removable in `tighten-doc`).
+- Drop weak quoted phrases first, not strong ones. Use the 80% threshold to decide which are weak.
+- DO NOT shorten the capability one-liner — that's the routing anchor. Trim the lists instead.
+
+## Don'ts
+
+- Don't stuff implementation skill names in the description. They belong in the body. The description must compete with sibling skills on keyword density.
+- Don't list every possible synonym. Pick the realistic ones; over-listing dilutes precision.
+- Don't write the Proactively-invoke clause as "...and asks for opinion or review" — that hijacks every review-type sibling.
+- Don't use abstract capability words like "comprehensive", "robust", "nuanced" — they don't help routing models match against utterances.
+- Don't make the description claim something the skill body contradicts. Cross-check: if description says "X is in scope", the body must not say "for X, route to Y".
+- Don't put advisory-only language in Skip-when (e.g. "consider whether..."). Skip-when must name concrete routing targets.
+- Don't add new sanitized labels (angle-bracket capability tokens like `<some-capability>`) without registering them in the maintainer's private alias YAML first. See R0 in the parent skill.
+
+## Validation checklist
+
+Before committing a description rewrite:
+
+- [ ] YAML parses with `YAML.safe_load(frontmatter_raw, aliases: false)`. If you use `|` block scalar (recommended for multi-line), validators must rescue `Psych::Exception` (covers `SyntaxError` AND `BadAlias`), not only `Psych::SyntaxError`.
+- [ ] `desc.length <= 800` chars after YAML parse.
+- [ ] All four sections present in order: capability / Use-when / Proactively-invoke / Skip-when. This applies to routing/workflow/cross-cutting skills; stack-specific implementation skills may keep the shorter capability-plus-quoted-triggers form (see "When this reference applies").
+- [ ] Every quoted Use-when phrase passes the 80% precision threshold or is anchored.
+- [ ] Proactively-invoke clause has a "do not invoke when ..." negative or a "Skip when ..." reverse-trigger covering the most likely over-fire.
+- [ ] Skip-when names concrete `→ skill-name` targets, not abstract criteria.
+- [ ] No business nouns, project paths, repo names, or source-team identifiers leaked.
+- [ ] Description doesn't contradict the skill body — grep body for the capability words in the description; any "this skill does not own X" lines in body must match Skip-when in description.
+- [ ] No new angle-bracket sanitized labels (`<...>`) appear in the description that are not registered in the maintainer's private alias YAML (see R0).
+- [ ] If this is a routing/workflow skill, descriptions cover at least 2–3 sibling collision cases in Skip-when (real collisions, observed or likely).
+- [ ] If there is an observed or likely routing collision with a named injected process-skill class (e.g. an injected brainstorming/scope-shaping skill) over the same request class, the description carries native-language delivery utterances (80%-precise or anchored) AND a scoped entry-ownership clause (see "Precedence against session-injected process skills"). Do not add this for merely theoretical overlap.
+- [ ] Sanity check: read the description as a future AI router would. Would it pick this skill for the intended utterances and reject for the unintended ones? If unclear, the description is too vague.
+
+## Iterative challenge discipline
+
+A description rewrite is a routing-surface change, not a wording-only edit. The wording-only exception in the dual-track-review-gate (`references/dual-track-review-gate.md`) does NOT cover description rewrites. Run an adversarial challenge against the new description that explicitly asks:
+
+- Do any quoted phrases collide with sibling skills?
+- Does the Proactively-invoke clause over-fire on common situations?
+- Does the description claim anything the body contradicts?
+- Are there utterances in the skill's intended territory that none of the triggers would catch?
+
+Re-run the challenge after each fix-up. Multiple rounds are normal: in practice 2–3 iterations land a stable description.
+
+## Iteration after deployment
+
+Even a carefully written description will miss real-user phrasings. Plan to collect actual miss / over-trigger reports for 1–2 weeks after landing, then increment the trigger list and Skip-when based on data. Do not pre-emptively stuff in every imaginable phrase — that fails the 80% threshold and creates new collisions.