kc-beta 0.1.2 → 0.3.0

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

@@ -3,233 +3,112 @@ name: skill-authoring
 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
 
-## 核心原则
+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 Folder Structure
 
-## 技能文件夹结构
-
-每条规则的技能文件夹位于 `rule-skills/` 目录下，命名规范为 `R{编号}-{英文短名}/`：
+Follow the official Claude Code skill format strictly. See `references/skill-format-spec.md` for the complete specification.
 
 ```
-rule-skills/R001-invoice-date-validity/
-├── SKILL.md              # 核查逻辑的完整描述（技能主文件）
-├── scripts/              # 确定性操作的代码脚本
-│   ├── extract_date.py   # 日期字段提取
-│   └── validate.py       # 格式校验逻辑
-├── references/           # 法规原文及解读
-│   └── regulation.md     # 相关法规条文的逐字摘录
-├── assets/               # 样本数据和边界案例
-│   ├── samples.json      # 测试样本（含预期结果）
-│   └── corner_cases.json # 边界案例集
-└── CHANGELOG.md          # 变更记录
+rule-skills/
+  rule-001-capital-adequacy/
+    SKILL.md            # The verification logic and methodology
+    scripts/
+      check.py          # Deterministic checks (regex, calculations)
+    references/
+      regulation.md     # Original regulation text, verbatim
+      interpretation.md # Expert notes on how to interpret edge cases
+    assets/
+      samples.json      # Annotated sample extractions with expected results
+      corner_cases.json # Known edge cases with their resolutions
 ```
 
-## 编写 SKILL.md
+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 是技能文件夹的灵魂。编程智能体在执行核查时首先读取这个文件，它必须提供足够清晰的指导。
+## Writing SKILL.md
 
-### 前置元数据（Frontmatter）
+### Frontmatter
 
 ```yaml
 ---
-name: R001-invoice-date-validity
-description: Verify that invoice date falls within the contract validity period and complies with statutory time limits. Use when processing invoices against their corresponding contracts. Checks date format, date range, and cross-references with contract effective/expiry dates.
+name: rule-001-capital-adequacy
+description: Verify that the capital adequacy ratio reported in the document meets the regulatory minimum of 8%. Use when checking capital adequacy compliance in bank financial reports. Check the capital adequacy section or table for the reported ratio and compare against the threshold.
 ---
 ```
 
-**name 必须与文件夹名一致。**
-
-**description 要写得「强势」**——明确告诉系统什么时候该调用这个技能。不要含糊，要具体列出触发场景。description 保持英文以兼容系统调度。
-
-### 正文结构
+- **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.
 
-明确告诉编程智能体在单据中的什么位置去找需要核查的字段：
+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.
 
-- 发票上的「开票日期」字段——通常位于发票右上角区域
-- 合同中的「合同生效日期」和「合同到期日期」——通常位于合同首页或末页
-- 如果是电子发票，日期字段的 JSON 路径是 `invoice.issue_date`
+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%."
 
-规定字段提取后的标准化格式：
+### Length and Style
 
-- 所有日期统一转换为 `YYYY-MM-DD` 格式
-- 如果原始日期为中文格式（如「2025年3月15日」），需先解析为标准格式
-- 缺失字段标记为 `null`，不要猜测或填充默认值
+- 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.
 
-#### 四、判定逻辑
+## Pipeline Node Design
 
-用清晰的条件表达式描述核查逻辑：
+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.
 
-```
-IF 发票日期 IS NULL:
-    结论 = "无法核查"，原因 = "发票日期缺失"
-ELIF 合同生效日期 IS NULL OR 合同到期日期 IS NULL:
-    结论 = "无法核查"，原因 = "合同期限信息不完整"
-ELIF 发票日期 < 合同生效日期:
-    结论 = "不通过"，原因 = "发票开具日期早于合同生效日期"
-ELIF 发票日期 > 合同到期日期:
-    结论 = "不通过"，原因 = "发票开具日期晚于合同到期日期"
-ELSE:
-    结论 = "通过"
-```
+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.
 
-#### 五、边界情况与例外
-
-列举已知的特殊情形：
-
-- 合同存在展期或续签：以最新的到期日期为准
-- 开票日期恰好等于合同生效日期或到期日期：视为通过
-- 框架合同下的订单发票：以订单对应的执行期限为准，而非框架合同整体期限
-- 补开发票的情形：部分法规允许在合同到期后一定期限内补开
-
-#### 六、输出格式
-
-规定核查结果的标准输出结构：
-
-```json
-{
-  "rule_id": "R001",
-  "rule_name": "发票日期有效性",
-  "verdict": "pass | fail | unable_to_verify",
-  "confidence": 0.95,
-  "details": {
-    "invoice_date": "2025-03-15",
-    "contract_start": "2025-01-01",
-    "contract_end": "2025-12-31"
-  },
-  "comment": "发票日期在合同有效期内",
-  "source_ref": "《增值税发票管理办法》第十五条"
-}
-```
+## Writing Scripts
 
-#### 七、批注说明
-
-如果核查发现问题，批注（comment）应当专业、简洁、可操作：
-
-- 正例：「发票日期 2025-03-15 晚于合同到期日 2025-02-28，差异 15 天」
-- 反例：「日期有问题」——信息量不足，不可操作
-
-## 编写 scripts/
-
-scripts 目录存放确定性操作的 Python 脚本。规则是：**凡是不需要 LLM 判断的操作，都用代码实现。**
-
-适合用代码的操作：
-- 日期格式解析与标准化
-- 金额的数字与大写转换校验
-- 税率计算与验证
-- 正则表达式匹配（发票号码格式、统一社会信用代码格式）
-- 字段存在性检查
-
-不适合用代码的操作：
-- 从非结构化文本中提取语义信息
-- 判断描述性内容是否合规
-- 理解自然语言表述的业务含义
-
-脚本要求：
-- 纯 Python，不依赖重型第三方库（允许 `re`、`json`、`datetime` 等标准库）
-- 函数有清晰的输入输出类型注解
-- 包含基本的错误处理
-- 可独立运行测试
-
-## 编写 references/
-
-将与本规则直接相关的法规原文逐字摘录到 `references/regulation.md` 中。
-
-要求：
-- 逐字引用，不要改写或概括
-- 标注出处：法规名称、发布机构、文号、条款编号
-- 如果开发者用户对模糊条文给出了解读，以「业务解读」标注记录
-- 如果规则涉及多部法规，分段引用，注明各自适用范围
-
-这个文件的目的是让核查结论可追溯。任何核查结论都应该能在 references 中找到法规依据。
-
-## 编写 assets/
-
-### samples.json
-
-提供至少 3-5 个测试样本，覆盖以下场景：
-
-```json
-[
-  {
-    "id": "S001",
-    "description": "标准通过案例",
-    "input": { "invoice_date": "2025-06-15", "contract_start": "2025-01-01", "contract_end": "2025-12-31" },
-    "expected_verdict": "pass"
-  },
-  {
-    "id": "S002",
-    "description": "发票日期超出合同期限",
-    "input": { "invoice_date": "2026-02-01", "contract_start": "2025-01-01", "contract_end": "2025-12-31" },
-    "expected_verdict": "fail"
-  },
-  {
-    "id": "S003",
-    "description": "合同日期缺失",
-    "input": { "invoice_date": "2025-06-15", "contract_start": null, "contract_end": null },
-    "expected_verdict": "unable_to_verify"
-  }
-]
-```
+Scripts in `scripts/` handle deterministic operations:
 
-### corner_cases.json
+- **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).
 
-记录在测试过程中发现的边界案例，格式与 samples.json 一致，但额外包含 `discovered_in` 字段标注发现来源（测试轮次、生产核查等）。
+Scripts should be self-contained Python files that can be imported or executed. Include clear input/output documentation in the script's docstring.
 
-## 技能迭代
+Do not put LLM prompts in scripts. LLM interactions belong in the SKILL.md body or in the workflow (later phase).
 
-技能不是一次写完就定型的。通过测试和实际核查，技能会不断演化。
+## Writing References
 
-### 迭代触发条件
+`references/` holds content that the coding agent reads on demand:
 
-- 测试中发现误判（漏报或误报）
-- 开发者用户反馈规则描述不准确
-- 发现新的边界案例
-- 法规变更影响本规则
+- **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.
 
-1. 在 CHANGELOG.md 中记录变更内容、原因、日期
-2. 更新 SKILL.md 中的相关段落
-3. 如果变更涉及判定逻辑，同步更新 scripts/
-4. 将新发现的边界案例添加到 corner_cases.json
-5. 重新运行全部测试样本，确认无回归
+## Writing Assets
 
-### CHANGELOG.md 格式
+`assets/` holds data that supports testing and edge case handling:
 
-```markdown
-## v1.1 - 2025-04-01
-- 新增边界案例：框架合同下的订单发票处理逻辑
-- 修正判定逻辑：开票日期等于合同到期日视为通过
-- 来源：第二轮测试反馈
+- **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.
 
-## v1.0 - 2025-03-20
-- 初始版本，基于《增值税发票管理办法》第十五条提取
-```
+## 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.md 正文使用待核查单据的语言：
+Use the bundled `skill-creator` skill if you want to run the full eval/iterate workflow with quantitative benchmarks.
 
-- 核查中文单据 → 正文写中文
-- 核查英文单据 → 正文写英文
-- 核查中英双语单据 → 正文写中文，关键英文术语保留原文
+## Bilingual Skills
 
-frontmatter 中的 name 和 description 始终使用英文，以确保系统层面的兼容性。
+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.