kc-beta 0.8.1 → 0.8.3

package/template/skills/zh/skill-authoring/SKILL.md

@@ -4,29 +4,29 @@ tier: meta
 description: Write each verification rule into a Claude Code skill folder following the official skill format. Use when converting extracted rules into skill folders, when iterating on existing rule skills after testing, or when the developer user wants to capture domain knowledge as a skill. Each skill folder must be self-contained with business logic in SKILL.md, code in scripts/, regulation context in references/, and sample data in assets/. Also use the bundled skill-creator for the full eval/iterate workflow.
 ---
 
-# Skill Authoring
+# 技能编写（Skill Authoring）
 
-Each verification rule becomes a skill folder. The skill must be self-contained: anyone (or any agent) reading just this folder should have everything needed to verify compliance with that one rule.
+每条核查规则变成一个 skill 目录。这个 skill 必须自包含：任何人（或任何 agent）只读这一个目录就该有能力对这条规则做合规核查。
 
-## Skill Folder Structure
+## Skill 目录结构
 
-Follow the official Claude Code skill format strictly. See `references/skill-format-spec.md` for the complete specification.
+严格遵循官方 Claude Code skill 格式。完整规范见 `references/skill-format-spec.md`。
 
 ```
 rule-skills/
   rule-001-capital-adequacy/
-    SKILL.md            # The verification logic and methodology
+    SKILL.md            # 核查逻辑与方法论
     scripts/
-      check.py          # Deterministic checks (regex, calculations)
+      check.py          # 确定性核查（正则、算术）
     references/
-      regulation.md     # Original regulation text, verbatim
-      interpretation.md # Expert notes on how to interpret edge cases
+      regulation.md     # 原始源文本，照抄
+      interpretation.md # 对边缘情形的解读笔记
     assets/
-      samples.json      # Annotated sample extractions with expected results
-      corner_cases.json # Known edge cases with their resolutions
+      samples.json      # 已标注的样本抽取与期望结果
+      corner_cases.json # 已知边缘案例与处理方式
 ```
 
-Not every rule needs all of these. A simple threshold check might only need SKILL.md and a script. A complex semantic rule might need detailed references and many samples. Start minimal, add as needed during testing.
+不是每条规则都需要全部文件。简单阈值核查可能只要 SKILL.md + 一个脚本；复杂语义规则可能需要详尽的 references 和大量样本。从最小开始，测试期间按需加。
 
 **文件名大小写很重要。** 必须使用大写 `SKILL.md`（与 `template/skills/` 中的 meta-skill 约定一致）。Linux 文件系统区分大小写；引擎的路径匹配、审计脚本、下游工具都假定为大写。不要写成 `skill.md`、`Skill.md` 或其他大小写变体。
 
@@ -43,9 +43,9 @@ Not every rule needs all of these. A simple threshold check might only need SKIL
 
 ### 反模式：统一运行器（unified runner）
 
-如果你发现自己在写一个 `unified_qc.py`（或 `batch_runner.py`、`master_check.py`）把全部 110 条规则塞进一个 Python 文件里，**停下来**。这说明你的单条规则技能写错了，不是架构错了。请修复单条技能。
+如果你发现自己在写一个 `unified_qc.py`（或 `batch_runner.py`、`master_check.py`）把全部规则塞进一个 Python 文件里，**停下来**。这说明你的单条规则技能写错了，不是架构错了。请修复单条技能。
 
-E2E #4 给出了代价：智能体写了一个 `unified_qc.py` 绕过它不信任的 110 个独立技能。结果是 6,930 条生产检查里出了 1,150 个错误（16.6%），相位计数器卡在 `production_qc`，而真实工作还在 skill_authoring 里进行。统一运行器在局部看起来很高效，全局上是个错误。
+一种值得警惕的失败模式：智能体写一个 `unified_qc.py` 类型的统一执行器来绕过它不信任的独立技能。结果是错误级联——一条规则的失败会把所有其他规则的判定一起带崩，很容易在数千次生产核查上做出 15%+ 的错误率。统一执行器在局部看起来很高效，全局上是个错误。它还会卡住阶段模型：磁盘上根本没有独立的 `check.py` 文件落地，引擎就没法把这部分工作计入里程碑。
 
 如果某些独立技能跑不通，正确的应对是定位并修复出问题的那几条，而不是合并所有技能。整个流水线（extraction → skill_testing → distillation → production_qc）的前提就是「一条规则 = 一个可独立验证的产物」。
 
@@ -53,22 +53,24 @@ E2E #4 给出了代价：智能体写了一个 `unified_qc.py` 绕过它不信
 
 每个 rule_skill 目录都必须 **同时** 拥有有内容的 `SKILL.md` **和** 有内容的 `check.py`（或 check.py 通过 import 调用一个真正做事的 workflow）。任何一边是桩都破坏了契约。
 
-**变体 1（v0.7.5 贷款 审计 § 9.1）**：桩 `SKILL.md`（19 行模板，`检查逻辑: N/A`）配上真实的 `check.py`（44-131 行正则方法论）。SKILL.md 本该是人类可读的方法论文档。读者扫一眼规则目录想了解"这条核查什么、为什么核查"，结果什么都看不到。智能体把方法论塞进了 `check.py` 的注释里，引擎能跑，但产物的语义就丢了。
+**变体 1**：桩 `SKILL.md`（一份约 20 行的模板脚手架，里面写着 `检查逻辑: N/A` 或类似内容）配上真实的 `check.py`（把正则方法论塞在代码注释里）。SKILL.md 本该是人类可读的方法论文档。读者扫一眼规则目录想了解"这条核查什么、为什么核查"，结果什么都看不到。方法论被推进了 `check.py` 的注释里——引擎能跑，但产物的语义就丢了。
 
-**变体 2（v0.7.5 资管 审计 § 3.4）**：有内容的 `SKILL.md`（真实方法论、PASS/FAIL 判定标准、法规交叉引用）配上桩 `check.py`（29 行脚手架，永远返回 `{"verdict": "NOT_APPLICABLE", "evidence": "Check requires worker LLM execution"}`）。真正的核查逻辑在 `workflows/<rule_id>/workflow.py` 里 —— 但 `check.py` 既没 import 也没调用。用户执行 `python rule_skills/R01-01/check.py document.txt` 任意输入都得到 `NOT_APPLICABLE`，结果是误导性的。
+**变体 2**：有内容的 `SKILL.md`（真实方法论、PASS/FAIL 判定标准、源文交叉引用）配上桩 `check.py`（一份薄脚手架，永远返回 `{"verdict": "NOT_APPLICABLE", "evidence": "Check requires worker LLM execution"}`）。真正的核查逻辑在 `workflows/<rule_id>/workflow.py` 里 —— 但 `check.py` 既没 import 也没调用。用户执行 `python rule_skills/R01-01/check.py document.txt` 任意输入都得到 `NOT_APPLICABLE`，结果是误导性的。
 
-**变体 3（历史遗留 v0.7.0）**：桩 `check.py` 返回 `{"pass": null, "method": "stub"}`，SKILL.md 写得还行。方法论描述出来了，但没有可执行实现。
+**变体 3（历史遗留）**：桩 `check.py` 返回 `{"pass": null, "method": "stub"}`，SKILL.md 写得还行。方法论描述出来了，但没有可执行实现。
+
+**变体 4（"单体 verify_engine 桩"）**：每条规则的 SKILL.md 都是一份 20-35 行的薄脚手架（"详见 verify_engine.py"），每条规则的 check.py 都是一段薄 shim，import 并调用一个根目录下的单体 `rule_skills/verify_engine.py`（或类似文件）—— 后者把全部 15-20 条规则的核查逻辑塞在一个 ~750 行的大文件里。每条规则的 check.py 都长这样：`from rule_skills.verify_engine import check_R01_01; return check_R01_01(doc)`。这能通过"check.py 不是字面意义上的桩"这道表面检查，但它颠倒了规范的"每规则一个粒度单元"的设计：每条规则的文件不含规则特定的推理，单体文件持有一切，"读这条 skill 就能理解这条规则"的工作流对所有人（开发者用户、未来审计者、下游 agent）都失效了。契约里之所以把 skill 定义为 KC 每条规则的粒度单元，是有原因的。把所有核查逻辑集中到一个大文件里看上去高效，实质上失去了"按规则审计"这个本意。如果你发现自己在写一个 `verify_engine.py`，里面有 15 个以上的 check 函数，而每条规则只有桩 SKILL.md / 桩 check.py，停下 —— 把方法论留在每条规则的 SKILL.md 里（要有内容），check 逻辑要么内联到每条规则的 check.py，要么走规范的"per-rule check.py + workflow_v1.py"模式。
 
 **契约**：
-- ✓ DO：SKILL.md 描述「核查什么」「为什么核查」「什么时候触发」。要有内容 —— 通常 50-300 行，不是 19 行模板。
+- ✓ DO：SKILL.md 描述「核查什么」「为什么核查」「什么时候触发」。要有内容 —— 通常 50-300 行，不是一份 20 行的模板。
 - ✓ DO：check.py 实现核查。**要么** 直接写有实质的逻辑，**要么** `from workflows.<rule_id>.workflow_v1 import verify` 然后委托给它。返回具体的判定。
 - ✗ DON'T：SKILL.md 是桩、方法论塞在 check.py 注释里（变体 1）。
 - ✗ DON'T：SKILL.md 有内容，但 check.py 返回 NOT_APPLICABLE 且不委托给 workflow（变体 2）。
 - ✗ DON'T：check.py 返回 null verdict（变体 3，历史遗留）。
 
-未来的引擎里程碑检查（v0.8 P2-F）可能在 check.py 桩比例过高时拒绝阶段推进。现在就写得有内容更省事。
+引擎可能在 check.py 桩比例过高时拒绝阶段推进。现在就写得有内容更省事。
 
-## Writing SKILL.md
+## 编写 SKILL.md
 
 ### Frontmatter
 
@@ -79,49 +81,44 @@ description: Verify that the capital adequacy ratio reported in the document mee
 ---
 ```
 
-- **name**: Must match the directory name exactly. Use lowercase, hyphens, no spaces. Prefix with the rule ID from your catalog.
-- **description**: Write it as if explaining to another coding agent when they should use this skill. Be specific about what the rule checks, where to look in the document, and what constitutes pass/fail. Be pushy — include trigger keywords.
-
-### Body Content
-
-The body should cover:
-
-1. **What this rule checks** — one paragraph explaining the rule in plain language. Include the regulatory source and intent.
-
-2. **Where to look** — which section, chapter, table, or part of the document contains the relevant information. Be specific. "The capital adequacy ratio is typically found in Chapter 2, Section 'Key Regulatory Metrics' or in the summary table on page 1."
-
-3. **What to extract** — the specific entities needed. "Extract the reported capital adequacy ratio as a percentage." Define the expected format and any normalization needed.
+- **name**：必须与目录名完全一致。小写、用连字符，不要空格。前缀用目录里的 rule ID。
+- **description**：当作在向另一个 coding agent 解释"什么时候该用这个 skill"来写。说清楚这条规则核查什么、要去文档的哪里看、什么算 pass/fail。写得"主动"一点 —— 把触发关键词都带上。
 
-4. **How to judge** — the logic for pass/fail. "The ratio must be >= 8.0%. If the ratio is missing, flag as MISSING rather than FAIL." For semantic judgments, describe the criteria in natural language.
+### 正文内容
 
-5. **Edge cases** — known tricky situations. "Some reports express the ratio as a decimal (0.12) rather than a percentage (12%). Normalize before comparing."
+正文应当覆盖：
 
-6. **Comment format** — what to say when the rule fails. Keep it concise and actionable. "Capital adequacy ratio is X%, which is below the regulatory minimum of 8%."
+1. **这条规则核查什么** —— 用一段平白的话解释规则。带上源文出处和意图。
+2. **去哪里看** —— 哪一节、哪一章、哪张表、文档哪一部分。写具体。"资本充足率通常在第 2 章「关键监管指标」一节，或在第 1 页的汇总表中。"
+3. **要抽什么** —— 具体的实体。"抽出报告中的资本充足率，以百分比表示。"明确期望的格式与必要的归一化。
+4. **怎么判** —— pass/fail 逻辑。"比率须 ≥ 8.0%。如果比率缺失，标记为 MISSING 而不是 FAIL。"语义判断时，用自然语言描述判定标准。
+5. **边缘情形** —— 已知的棘手情况。"有些报告把比率写成小数（0.12）而非百分比（12%），比较前先归一化。"
+6. **comment 格式** —— 规则失败时该说什么。简洁、可操作。"资本充足率为 X%，低于监管下限 8%。"
 
-### Length and Style
+### 篇幅与风格
 
-- Keep SKILL.md under 500 lines. Most rules should be 100-200 lines.
-- Explain the WHY behind the rule, not just the mechanics. Understanding intent helps handle edge cases.
-- Write in imperative form: "Extract the ratio" not "The ratio should be extracted."
-- If detailed regulation text is long, put it in `references/regulation.md` and reference it from SKILL.md.
+- SKILL.md 控制在 500 行以内。大多数规则在 100-200 行。
+- 解释规则**为什么**这样定，而不是只描述机械流程。理解意图有助于处理边缘情形。
+- 用祈使句："Extract the ratio"，不要写"The ratio should be extracted"。
+- 如果详细源文较长，放进 `references/regulation.md`，在 SKILL.md 里引用。
 
-## Pipeline Node Design
+## Pipeline 节点设计
 
-When a skill's workflow has multiple steps, decompose into nodes where each node does one thing well. Each node's difficulty should be well within the model's capability — don't cram location + extraction + judgment into a single LLM call.
+当一条 skill 的 workflow 有多个步骤时，拆成多个节点，每个节点把一件事做好。每个节点的难度都要在模型能力范围内 —— 不要把 location + extraction + judgment 全塞到一次 LLM 调用里。
 
-Pre-processing (text cleaning, format normalization) and post-processing (output parsing, value normalization) are separate nodes, not embedded in the LLM prompt. This keeps prompts clean and makes each step independently testable.
+预处理（文本清洗、格式归一化）和后处理（输出解析、数值归一化）是独立节点，不要嵌进 LLM 提示词。这能保持提示词干净，且每一步可独立测试。
 
-## Writing Scripts
+## 编写 Scripts
 
-Scripts in `scripts/` handle deterministic operations:
+`scripts/` 下的脚本负责确定性操作：
 
-- **Regex patterns** for entity extraction (dates, amounts, ratios, identifiers).
-- **Calculation logic** for threshold checks, ratio computations, cross-field validation.
-- **Format normalization** (Chinese numerals → digits, date format standardization, unit conversion).
+- **正则模式**用于实体抽取（日期、金额、比率、标识符）。
+- **算术逻辑**用于阈值核查、比率计算、跨字段校验。
+- **格式归一化**（中文数字 → 阿拉伯数字、日期格式标准化、单位转换）。
 
-Scripts should be self-contained Python files that can be imported or executed. Include clear input/output documentation in the script's docstring.
+脚本应该是自包含的 Python 文件，既可被 import 也可被执行。在 docstring 中说明输入/输出。
 
-Do not put LLM prompts in scripts. LLM interactions belong in the SKILL.md body or in the workflow (later phase).
+不要把 LLM 提示词写在脚本里。LLM 交互属于 SKILL.md 正文或属于 workflow（后续阶段）。
 
 ### 关键字匹配前先剥除审核者注解
 
@@ -139,35 +136,77 @@ def check(document_text):
 
 已识别的前缀（中英文）：预期命中点、预期结果、预期判定、预期验证、标注、审核标注、Expected、expected、EXPECTED、Annotation、annotation。如果你的项目用了别的标签，传 `extra_prefixes=("...", "...")`。
 
-E2E #11 贷款 v0.8 审计：14 条规则里有 4 条独立运行 check.py 时在违规样本上 false-positive PASS，因为匹配到的是 `预期命中点: ...年化利率` 尾注而不是文档正文。v0.8.1 把这个工具作为模板文件随包发布，import 一行就能避开这个坑。
+一种值得警惕的失败模式：相当一部分规则在独立运行 check.py 时会在违规样本上 false-positive PASS，原因是正则匹配到的是 `预期命中点: ...` 尾注，而不是文档正文。KC 把这个工具作为模板文件随包发布，import 一行就能避开这个坑。
+
+## 编写 References
+
+`references/` 放 coding agent 按需读取的内容：
+
+- **regulation.md**：原始源文本，照抄。带上出处、日期、版本。这是规则所依据的 ground truth。
+- **interpretation.md**：开发者用户的专家笔记，或 coding agent 自己分析得来的笔记。"当源文说'充分披露'时，实践中意味着该章节至少有 2 段、覆盖风险 A、B、C。"
+
+References 要事实化、要有来源。它们是证据，不是指令。
+
+## 编写 Assets
+
+`assets/` 放支撑测试与边缘案例处理的数据：
+
+- **samples.json**：标注过的样例。每条记录：输入（抽取出来的文本或实体）、期望结果（pass/fail/missing）、期望 comment。在测试过程中逐步累积。
+- **corner_cases.json**：标准逻辑不处理的边缘案例。每条记录：描述、检测模式、处理方式、置信度阈值。方法学见 `corner-case-management` skill。
+
+## 编写方法论（来自 skill-creator 核心）
+
+这一节把 Anthropic 上游 `skill-creator` 里通用的编写模式整合进来。起草任何 KC 规则技能时，在上文的 KC 专属布局之上叠加应用这些模式。
+
+### 先捕捉意图，再起草
+
+在写任何技能之前，先把四个问题想清楚：
+
+1. **这个技能要让 Claude（或 check.py）做什么？** —— 一个具体的能力，不是一类能力。
+2. **它应该在什么时候触发？** —— 什么样的用户话术 / 文档语境应该匹配它的 description。
+3. **期望的输出格式是什么？** —— verdict + comment + evidence 的形态；非检查类技能则给出交付物的形态。
+4. **要不要准备测试样本？** —— 如果这条规则有客观的通过/失败判定（KC 几乎所有规则都是），那就要。`assets/samples.json` 应该在遇到边界情况时增量地写。
+
+如果对话里已经有了实际例子（用户指着一段文字说"这不合规"），先从对话历史里抽取答案——不要让用户把已经说过的话再说一遍。
+
+### Frontmatter 与渐进式信息披露
+
+技能按三个层级加载，每层各有合适的容量：
+
+1. **元数据（name + description）** —— 始终在代理上下文里。约 100 词。这是**最主要的触发机制**——要写得具体、稍微"催促"一点（Claude 倾向于触发不足）。在里面包含触发关键词、规则编号、来源法规、以及它期望在文档哪里找到证据。
+2. **SKILL.md 正文** —— 技能被触发时加载。典型规则的目标长度是 100–300 行，硬上限 500 行。要解释规则背后的"为什么"，不要只讲机械操作。
+3. **打包资源**（scripts/、references/、assets/）—— 只有正文显式指向它们时才会被加载。大段的法规原文和样本语料应当放在这里，而不是塞在正文里。
+
+如果 SKILL.md 接近 500 行，那就是该把细节下沉到 `references/` 的信号——在正文里留一个指向："详尽的边界情况枚举见 references/edge-cases.md。"
 
-## Writing References
+### 写作风格
 
-`references/` holds content that the coding agent reads on demand:
+- **祈使句优于被动语态。** "提取这一比率"好过"该比率应被提取"。
+- **解释为什么，不只是是什么。** 今天的 LLM 有不错的心智理论——只要一句"这条法规是为了保护零售投资者"，下游代理就能把你没有枚举到的情形泛化处理。
+- **警惕大写 MUST 和 NEVER。** 一旦你想伸手去写它们，通常意味着背后的道理没有讲清楚。换个说法、把道理讲出来。
+- **位置要具体。** "在第二章「主要监管指标」一节或者首页的汇总表里找"比"在财务披露里某个地方找"要好得多。
 
-- **regulation.md**: The original regulation text, verbatim. Include the source, date, and version. This is the ground truth that the rule is derived from.
-- **interpretation.md**: Expert notes from the developer user or from the coding agent's own analysis. "When the regulation says 'adequate disclosure', in practice this means the section must be at least 2 paragraphs and cover risks A, B, and C."
+### 先写测试样本，再写脚本
 
-Keep references factual and sourced. They are evidence, not instructions.
+写完 SKILL.md 之后，在 `assets/samples.json` 里写 2–3 个贴近现实的样本输入和它们的预期判定，**再去**最终敲定 `check.py`。样本为脚本提供锚点：你写的每条正则、每个关键字，都是为了让某个具体样本得到它的预期判定。脱离样本凭空写脚本，几乎一定会过拟合，在第一份真实文档上就会失效。
 
-## Writing Assets
+### 迭代，不要追求一次到位
 
-`assets/` holds data that supports testing and edge case handling:
+规则技能很少能在第一稿就写对。请预设至少要经过一轮测试暴露问题后的修订。不要为了应付每一个边界情况而堆砌防御性的 MUST——把方法论本身泛化一下更合算。如果三个样本各自都需要一个一次性的补丁，那是个信号：这条规则的陈述本身就太窄了。
 
-- **samples.json**: Annotated examples. Each entry: the input (extracted text or entity), the expected result (pass/fail/missing), and the expected comment. Build this incrementally as you test.
-- **corner_cases.json**: Edge cases that the standard logic does not handle. Each entry: description, detection pattern, resolution, and confidence threshold. See the `corner-case-management` skill for the methodology.
+如果你需要的方法论比这一节覆盖的更精细——例如带定量基准的正式评估循环、技能不同版本之间的盲式 A/B 对比、或者运行 description 优化器——请参考 `skill-creator`。
 
-## Iteration
+## 迭代
 
-Skills evolve through testing. After each test iteration:
-1. Update SKILL.md if the logic needs adjustment.
-2. Add failing cases to `assets/samples.json`.
-3. Add newly discovered edge cases to `assets/corner_cases.json`.
-4. Update `references/interpretation.md` with new insights.
-5. Log what changed and why.
+Skill 通过测试不断演化。每一轮测试之后：
+1. 如果逻辑需要调整，更新 SKILL.md。
+2. 把失败案例加进 `assets/samples.json`。
+3. 把新发现的边缘案例加进 `assets/corner_cases.json`。
+4. 把新的洞察加进 `references/interpretation.md`。
+5. 记录改了什么、为什么改。
 
-Use the bundled `skill-creator` skill if you want to run the full eval/iterate workflow with quantitative benchmarks.
+如果你想跑完整的 eval/iterate workflow 并拿到量化基准，使用随包的 `skill-creator` skill。
 
-## Bilingual Skills
+## 双语 Skill
 
-Write skills in the language matching the LANGUAGE setting in `.env`. If rules and documents are in Chinese, write the SKILL.md body in Chinese using proper financial/regulatory terminology. The frontmatter (name, description) stays in English for system compatibility.
+按 `.env` 中 LANGUAGE 设置的语言来写 skill。如果规则和文档都是中文，SKILL.md 正文也用中文写，使用恰当的金融/监管术语。Frontmatter（name、description）保持英文以保证系统兼容性。

package/template/skills/zh/skill-authoring/references/skill-format-spec.md

@@ -1,20 +1,20 @@
-# Claude Code Skill Format Specification
+# Claude Code 技能格式规范
 
-Distilled from the official Anthropic skill-creator. This is the authoritative reference for writing correctly formatted skill folders.
+提炼自 Anthropic 官方的 skill-creator。本文档是编写格式正确的技能目录的权威参考。
 
-## Skill Folder Structure
+## 技能目录结构
 
 ```
 skill-name/
-├── SKILL.md          (required)  Metadata + instructions
-├── scripts/          (optional)  Executable code
-├── references/       (optional)  Detailed documentation, loaded on demand
-└── assets/           (optional)  Templates, data files, images
+├── SKILL.md          (必需)  元数据 + 指令
+├── scripts/          (可选)  可执行代码
+├── references/       (可选)  详细文档，按需加载
+└── assets/           (可选)  模板、数据文件、图片
 ```
 
-The directory name must match the `name` field in SKILL.md frontmatter exactly.
+目录名必须与 SKILL.md frontmatter 中的 `name` 字段完全一致。
 
-## SKILL.md Format
+## SKILL.md 格式
 
 ### Frontmatter (YAML)
 
@@ -25,54 +25,54 @@ description: What this skill does and when to use it.
 ---
 ```
 
-**Required fields:**
+**必填字段：**
 
-| Field | Constraints |
+| 字段 | 约束 |
 |-------|-------------|
-| `name` | Max 64 chars. Lowercase letters, numbers, hyphens only. No leading/trailing/consecutive hyphens. Must match parent directory name. |
-| `description` | Max 1024 chars. Non-empty. Describe what it does AND when to use it. |
+| `name` | 最多 64 字符。只能含小写字母、数字、连字符。开头/结尾不可有连字符，不可出现连续连字符。必须与父目录名一致。 |
+| `description` | 最多 1024 字符。非空。同时描述技能"做什么"以及"何时使用"。 |
 
-**Optional fields:** `license`, `compatibility`, `metadata`
+**可选字段：** `license`、`compatibility`、`metadata`
 
-### Description Best Practices
+### Description 写作要点
 
-The description is the primary triggering mechanism — Claude uses it to decide when to invoke the skill. Make descriptions "pushy" to combat under-triggering:
+description 是技能的主要触发机制——Claude 依靠它决定是否调用这个技能。写得"主动"一些，以对抗触发不足：
 
-- Include both capability AND trigger contexts.
-- Use specific keywords the user might mention.
-- List concrete use cases.
-- State what NOT to use it for.
-- Aim for 100-200 words.
+- 同时包含能力描述与触发场景。
+- 使用用户实际可能会说出的关键词。
+- 列举具体的使用场景。
+- 说明**不适用**的场景。
+- 篇幅控制在 100-200 字之间。
 
-### Markdown Body
+### Markdown 正文
 
-Following the frontmatter, write instructions in Markdown. Guidelines:
+紧接 frontmatter，用 Markdown 写指令。遵循以下原则：
 
-- **Under 500 lines.** If approaching this, move detail to references/.
-- **Imperative form.** "Extract the value" not "The value should be extracted."
-- **Explain the why** behind instructions, not just the what.
-- **Include examples** when they clarify the expected behavior. One or two well-chosen examples beat ten mediocre ones.
+- **少于 500 行。** 接近上限时，把细节挪到 references/。
+- **祈使句式。** 写"抽取该值"，不写"该值应被抽取"。
+- **解释 why**，不仅解释 what。
+- **配示例**，当示例能澄清预期行为时。一两个精挑细选的好示例胜过十个平庸的。
 
-## Progressive Disclosure
+## 渐进式披露
 
-Skills use three-level loading:
+技能采用三级加载：
 
-1. **Metadata** (name + description): Always in context. ~100 tokens.
-2. **SKILL.md body**: Loaded when skill triggers. <500 lines ideal.
-3. **Bundled resources**: Loaded on demand. Unlimited size. Scripts can execute without loading.
+1. **元数据**（name + description）：始终在上下文中。约 100 tokens。
+2. **SKILL.md 正文**：技能触发时加载。最好少于 500 行。
+3. **打包的资源文件**：按需加载。不限大小。脚本可直接执行而无需加载。
 
-Reference files clearly from SKILL.md with guidance on when to read them. For large reference files (>300 lines), include a table of contents.
+在 SKILL.md 中清晰引用参考文件，并说明何时阅读它们。对较大的参考文件（> 300 行），加上目录。
 
-## File Referencing
+## 文件引用
 
-Use relative paths from the skill root:
+使用相对于技能根目录的路径：
 ```markdown
 See [the reference guide](references/regulation.md) for the full regulation text.
 Run the check script: `python scripts/check.py`
 ```
 
-## Naming Conventions
+## 命名规范
 
-- Directory names: lowercase with hyphens (`my-skill`, not `MySkill` or `my_skill`)
-- Keep names short and descriptive
-- For rule skills, prefix with the rule ID: `rule-001-capital-adequacy`
+- 目录名：小写并用连字符分隔（`my-skill`，而非 `MySkill` 或 `my_skill`）
+- 名称保持简短而具描述性
+- 对应规则的技能，按规则 ID 加前缀：`rule-001-capital-adequacy`