@shirayner/ace 0.1.0-snapshot.1

package/templates/skills/skill-creator/scripts/run_loop.py

@@ -0,0 +1,332 @@
+#!/usr/bin/env python3
+"""Run the eval + improve loop until all pass or max iterations reached.
+
+Combines run_eval.py and improve_description.py in a loop, tracking history
+and returning the best description found. Supports train/test split to prevent
+overfitting.
+"""
+
+import argparse
+import json
+import random
+import sys
+import tempfile
+import time
+import webbrowser
+from pathlib import Path
+
+import anthropic
+
+from scripts.generate_report import generate_html
+from scripts.improve_description import improve_description
+from scripts.run_eval import find_project_root, run_eval
+from scripts.utils import parse_skill_md
+
+
+def split_eval_set(eval_set: list[dict], holdout: float, seed: int = 42) -> tuple[list[dict], list[dict]]:
+    """Split eval set into train and test sets, stratified by should_trigger."""
+    random.seed(seed)
+
+    # Separate by should_trigger
+    trigger = [e for e in eval_set if e["should_trigger"]]
+    no_trigger = [e for e in eval_set if not e["should_trigger"]]
+
+    # Shuffle each group
+    random.shuffle(trigger)
+    random.shuffle(no_trigger)
+
+    # Calculate split points
+    n_trigger_test = max(1, int(len(trigger) * holdout))
+    n_no_trigger_test = max(1, int(len(no_trigger) * holdout))
+
+    # Split
+    test_set = trigger[:n_trigger_test] + no_trigger[:n_no_trigger_test]
+    train_set = trigger[n_trigger_test:] + no_trigger[n_no_trigger_test:]
+
+    return train_set, test_set
+
+
+def run_loop(
+    eval_set: list[dict],
+    skill_path: Path,
+    description_override: str | None,
+    num_workers: int,
+    timeout: int,
+    max_iterations: int,
+    runs_per_query: int,
+    trigger_threshold: float,
+    holdout: float,
+    model: str,
+    verbose: bool,
+    live_report_path: Path | None = None,
+    log_dir: Path | None = None,
+) -> dict:
+    """Run the eval + improvement loop."""
+    project_root = find_project_root()
+    name, original_description, content = parse_skill_md(skill_path)
+    current_description = description_override or original_description
+
+    # Split into train/test if holdout > 0
+    if holdout > 0:
+        train_set, test_set = split_eval_set(eval_set, holdout)
+        if verbose:
+            print(f"Split: {len(train_set)} train, {len(test_set)} test (holdout={holdout})", file=sys.stderr)
+    else:
+        train_set = eval_set
+        test_set = []
+
+    client = anthropic.Anthropic()
+    history = []
+    exit_reason = "unknown"
+
+    for iteration in range(1, max_iterations + 1):
+        if verbose:
+            print(f"\n{'='*60}", file=sys.stderr)
+            print(f"Iteration {iteration}/{max_iterations}", file=sys.stderr)
+            print(f"Description: {current_description}", file=sys.stderr)
+            print(f"{'='*60}", file=sys.stderr)
+
+        # Evaluate train + test together in one batch for parallelism
+        all_queries = train_set + test_set
+        t0 = time.time()
+        all_results = run_eval(
+            eval_set=all_queries,
+            skill_name=name,
+            description=current_description,
+            num_workers=num_workers,
+            timeout=timeout,
+            project_root=project_root,
+            runs_per_query=runs_per_query,
+            trigger_threshold=trigger_threshold,
+            model=model,
+        )
+        eval_elapsed = time.time() - t0
+
+        # Split results back into train/test by matching queries
+        train_queries_set = {q["query"] for q in train_set}
+        train_result_list = [r for r in all_results["results"] if r["query"] in train_queries_set]
+        test_result_list = [r for r in all_results["results"] if r["query"] not in train_queries_set]
+
+        train_passed = sum(1 for r in train_result_list if r["pass"])
+        train_total = len(train_result_list)
+        train_summary = {"passed": train_passed, "failed": train_total - train_passed, "total": train_total}
+        train_results = {"results": train_result_list, "summary": train_summary}
+
+        if test_set:
+            test_passed = sum(1 for r in test_result_list if r["pass"])
+            test_total = len(test_result_list)
+            test_summary = {"passed": test_passed, "failed": test_total - test_passed, "total": test_total}
+            test_results = {"results": test_result_list, "summary": test_summary}
+        else:
+            test_results = None
+            test_summary = None
+
+        history.append({
+            "iteration": iteration,
+            "description": current_description,
+            "train_passed": train_summary["passed"],
+            "train_failed": train_summary["failed"],
+            "train_total": train_summary["total"],
+            "train_results": train_results["results"],
+            "test_passed": test_summary["passed"] if test_summary else None,
+            "test_failed": test_summary["failed"] if test_summary else None,
+            "test_total": test_summary["total"] if test_summary else None,
+            "test_results": test_results["results"] if test_results else None,
+            # For backward compat with report generator
+            "passed": train_summary["passed"],
+            "failed": train_summary["failed"],
+            "total": train_summary["total"],
+            "results": train_results["results"],
+        })
+
+        # Write live report if path provided
+        if live_report_path:
+            partial_output = {
+                "original_description": original_description,
+                "best_description": current_description,
+                "best_score": "in progress",
+                "iterations_run": len(history),
+                "holdout": holdout,
+                "train_size": len(train_set),
+                "test_size": len(test_set),
+                "history": history,
+            }
+            live_report_path.write_text(generate_html(partial_output, auto_refresh=True, skill_name=name))
+
+        if verbose:
+            def print_eval_stats(label, results, elapsed):
+                pos = [r for r in results if r["should_trigger"]]
+                neg = [r for r in results if not r["should_trigger"]]
+                tp = sum(r["triggers"] for r in pos)
+                pos_runs = sum(r["runs"] for r in pos)
+                fn = pos_runs - tp
+                fp = sum(r["triggers"] for r in neg)
+                neg_runs = sum(r["runs"] for r in neg)
+                tn = neg_runs - fp
+                total = tp + tn + fp + fn
+                precision = tp / (tp + fp) if (tp + fp) > 0 else 1.0
+                recall = tp / (tp + fn) if (tp + fn) > 0 else 1.0
+                accuracy = (tp + tn) / total if total > 0 else 0.0
+                print(f"{label}: {tp+tn}/{total} correct, precision={precision:.0%} recall={recall:.0%} accuracy={accuracy:.0%} ({elapsed:.1f}s)", file=sys.stderr)
+                for r in results:
+                    status = "PASS" if r["pass"] else "FAIL"
+                    rate_str = f"{r['triggers']}/{r['runs']}"
+                    print(f"  [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:60]}", file=sys.stderr)
+
+            print_eval_stats("Train", train_results["results"], eval_elapsed)
+            if test_summary:
+                print_eval_stats("Test ", test_results["results"], 0)
+
+        if train_summary["failed"] == 0:
+            exit_reason = f"all_passed (iteration {iteration})"
+            if verbose:
+                print(f"\nAll train queries passed on iteration {iteration}!", file=sys.stderr)
+            break
+
+        if iteration == max_iterations:
+            exit_reason = f"max_iterations ({max_iterations})"
+            if verbose:
+                print(f"\nMax iterations reached ({max_iterations}).", file=sys.stderr)
+            break
+
+        # Improve the description based on train results
+        if verbose:
+            print(f"\nImproving description...", file=sys.stderr)
+
+        t0 = time.time()
+        # Strip test scores from history so improvement model can't see them
+        blinded_history = [
+            {k: v for k, v in h.items() if not k.startswith("test_")}
+            for h in history
+        ]
+        new_description = improve_description(
+            client=client,
+            skill_name=name,
+            skill_content=content,
+            current_description=current_description,
+            eval_results=train_results,
+            history=blinded_history,
+            model=model,
+            log_dir=log_dir,
+            iteration=iteration,
+        )
+        improve_elapsed = time.time() - t0
+
+        if verbose:
+            print(f"Proposed ({improve_elapsed:.1f}s): {new_description}", file=sys.stderr)
+
+        current_description = new_description
+
+    # Find the best iteration by TEST score (or train if no test set)
+    if test_set:
+        best = max(history, key=lambda h: h["test_passed"] or 0)
+        best_score = f"{best['test_passed']}/{best['test_total']}"
+    else:
+        best = max(history, key=lambda h: h["train_passed"])
+        best_score = f"{best['train_passed']}/{best['train_total']}"
+
+    if verbose:
+        print(f"\nExit reason: {exit_reason}", file=sys.stderr)
+        print(f"Best score: {best_score} (iteration {best['iteration']})", file=sys.stderr)
+
+    return {
+        "exit_reason": exit_reason,
+        "original_description": original_description,
+        "best_description": best["description"],
+        "best_score": best_score,
+        "best_train_score": f"{best['train_passed']}/{best['train_total']}",
+        "best_test_score": f"{best['test_passed']}/{best['test_total']}" if test_set else None,
+        "final_description": current_description,
+        "iterations_run": len(history),
+        "holdout": holdout,
+        "train_size": len(train_set),
+        "test_size": len(test_set),
+        "history": history,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run eval + improve loop")
+    parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
+    parser.add_argument("--skill-path", required=True, help="Path to skill directory")
+    parser.add_argument("--description", default=None, help="Override starting description")
+    parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
+    parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
+    parser.add_argument("--max-iterations", type=int, default=5, help="Max improvement iterations")
+    parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
+    parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
+    parser.add_argument("--holdout", type=float, default=0.4, help="Fraction of eval set to hold out for testing (0 to disable)")
+    parser.add_argument("--model", required=True, help="Model for improvement")
+    parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
+    parser.add_argument("--report", default="auto", help="Generate HTML report at this path (default: 'auto' for temp file, 'none' to disable)")
+    parser.add_argument("--results-dir", default=None, help="Save all outputs (results.json, report.html, log.txt) to a timestamped subdirectory here")
+    args = parser.parse_args()
+
+    eval_set = json.loads(Path(args.eval_set).read_text())
+    skill_path = Path(args.skill_path)
+
+    if not (skill_path / "SKILL.md").exists():
+        print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
+        sys.exit(1)
+
+    name, _, _ = parse_skill_md(skill_path)
+
+    # Set up live report path
+    if args.report != "none":
+        if args.report == "auto":
+            timestamp = time.strftime("%Y%m%d_%H%M%S")
+            live_report_path = Path(tempfile.gettempdir()) / f"skill_description_report_{skill_path.name}_{timestamp}.html"
+        else:
+            live_report_path = Path(args.report)
+        # Open the report immediately so the user can watch
+        live_report_path.write_text("<html><body><h1>Starting optimization loop...</h1><meta http-equiv='refresh' content='5'></body></html>")
+        webbrowser.open(str(live_report_path))
+    else:
+        live_report_path = None
+
+    # Determine output directory (create before run_loop so logs can be written)
+    if args.results_dir:
+        timestamp = time.strftime("%Y-%m-%d_%H%M%S")
+        results_dir = Path(args.results_dir) / timestamp
+        results_dir.mkdir(parents=True, exist_ok=True)
+    else:
+        results_dir = None
+
+    log_dir = results_dir / "logs" if results_dir else None
+
+    output = run_loop(
+        eval_set=eval_set,
+        skill_path=skill_path,
+        description_override=args.description,
+        num_workers=args.num_workers,
+        timeout=args.timeout,
+        max_iterations=args.max_iterations,
+        runs_per_query=args.runs_per_query,
+        trigger_threshold=args.trigger_threshold,
+        holdout=args.holdout,
+        model=args.model,
+        verbose=args.verbose,
+        live_report_path=live_report_path,
+        log_dir=log_dir,
+    )
+
+    # Save JSON output
+    json_output = json.dumps(output, indent=2)
+    print(json_output)
+    if results_dir:
+        (results_dir / "results.json").write_text(json_output)
+
+    # Write final HTML report (without auto-refresh)
+    if live_report_path:
+        live_report_path.write_text(generate_html(output, auto_refresh=False, skill_name=name))
+        print(f"\nReport: {live_report_path}", file=sys.stderr)
+
+    if results_dir and live_report_path:
+        (results_dir / "report.html").write_text(generate_html(output, auto_refresh=False, skill_name=name))
+
+    if results_dir:
+        print(f"Results saved to: {results_dir}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/templates/skills/skill-creator/scripts/utils.py

@@ -0,0 +1,47 @@
+"""Shared utilities for skill-creator scripts."""
+
+from pathlib import Path
+
+
+
+def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
+    """Parse a SKILL.md file, returning (name, description, full_content)."""
+    content = (skill_path / "SKILL.md").read_text()
+    lines = content.split("\n")
+
+    if lines[0].strip() != "---":
+        raise ValueError("SKILL.md missing frontmatter (no opening ---)")
+
+    end_idx = None
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        raise ValueError("SKILL.md missing frontmatter (no closing ---)")
+
+    name = ""
+    description = ""
+    frontmatter_lines = lines[1:end_idx]
+    i = 0
+    while i < len(frontmatter_lines):
+        line = frontmatter_lines[i]
+        if line.startswith("name:"):
+            name = line[len("name:"):].strip().strip('"').strip("'")
+        elif line.startswith("description:"):
+            value = line[len("description:"):].strip()
+            # Handle YAML multiline indicators (>, |, >-, |-)
+            if value in (">", "|", ">-", "|-"):
+                continuation_lines: list[str] = []
+                i += 1
+                while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith("  ") or frontmatter_lines[i].startswith("\t")):
+                    continuation_lines.append(frontmatter_lines[i].strip())
+                    i += 1
+                description = " ".join(continuation_lines)
+                continue
+            else:
+                description = value.strip('"').strip("'")
+        i += 1
+
+    return name, description, content

package/templates/skills/skill-optimize/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: skill-optimize
+description: >-
+  深度优化现有 Claude Code Skill 的方法论工具。基于认知科学、信息论、控制论提炼的七条永恒优化原则，
+  对 skill 进行系统性诊断和重构。
+  当用户想要改进、优化、精简现有 skill 时使用——无论目标是提升触发准确率、改善指令清晰度、
+  降低 token 消耗还是优化架构结构。
+  触发场景包括："优化这个 skill"、"skill 效果不好"、"skill 太长了"、"提升 skill 质量"、
+  "skill 触发不准"、"让这个 skill 更好"、"精简指令"、"optimize skill"、"improve skill"、
+  "refine skill instructions"、"skill not triggering correctly"，
+  或用户描述了某个现有 skill 的具体行为问题。
+  当用户想将结构化优化方法论应用于任何 Claude 使用的 skill 或指令集时也应触发。
+  不要在从零创建新 skill 或运行 eval benchmark 时触发——那些属于 skill-creator 的职责。
+  不要在与 Claude Code skill 无关的通用代码审查或重构时触发。
+---
+
+# Skill Optimize
+
+让现有 skill 变得更好的方法论。核心洞察：skill 质量来自理解 AI 如何处理指令，而非堆砌更多规则。
+
+> 一句话总结：在有限的认知带宽内，用最高信噪比的表达，传递让 AI 能够自主判断的认知协议。
+
+---
+
+## 本 Skill 与 skill-creator 的边界
+
+| 需求 | 使用 |
+|------|------|
+| 从零创建新 skill | skill-creator |
+| 运行 eval、benchmark、description 优化 | skill-creator |
+| 诊断 skill 为什么表现不佳 | **skill-optimize** |
+| 用原则方法论提升 skill 质量 | **skill-optimize** |
+| 重构臃肿或低效的 skill | **skill-optimize** |
+
+两者互补：用 skill-optimize 搞清楚"改什么、为什么改"，再用 skill-creator 的 eval 基础设施验证改进效果。
+
+---
+
+## 四步优化流程
+
+```
+诊断现状 → 选择原则 → 重构实施 → 验证效果
+    ↑                                    |
+    └────── 不满意？回到诊断 ─────────────┘
+```
+
+每次只改一个层面（触发 / 认知 / 资源），改完立即验证。不要批量修改——否则无法定位哪个改动起效。
+
+---
+
+## 第一步：诊断
+
+读取目标 skill 的 SKILL.md 和 references/，从四个维度评估：
+
+### 四维诊断
+
+**1. 触发准确率**
+- 该触发时触发了吗？（召回率）
+- 不该触发时安静吗？（精确率）
+- description 是否足够具体？是否与其他 skill 有边界混淆？
+
+**2. 任务完成质量**
+- 运行后输出是否满足需求？
+- 有没有反复出现的错误模式？
+- AI 是否误解了指令意图？
+
+**3. Token 效率**
+- 有没有指令导致 AI 做无用功？
+- 是否加载了不需要的上下文？
+- transcript 中有没有明显的浪费（长时间犹豫、重复尝试）？
+
+**4. 结构健康度**
+- SKILL.md 是否超过 500 行？
+- 原则与细节是否分层清晰？
+- references/ 是否被正确使用（深度知识在资源层，非堆在主体中）？
+
+基于诊断结果，识别最关键的 1-3 个问题。不要试图一次修复所有问题。
+
+---
+
+## 第二步：选择原则
+
+七条原则指导所有优化决策。每条解决一类失败模式。
+
+### 原则一：传意不传形
+
+**解决的问题**：AI 执行了指令的字面意思，却偏离了真实意图。
+
+解释*为什么*某事重要，而不只是*做什么*。Claude 具备心智理论——给出规则背后的原因，它能泛化到新场景。刚性规则（ALWAYS/NEVER）限制了这种泛化能力。
+
+**变换模式**：
+- 变换前："ALWAYS 用 bullet 列表"
+- 变换后："用 bullet 列表因为它们易于扫描——但当顺序重要时改用有序列表"
+
+**诊断信号**：统计 skill 中的 ALWAYS/NEVER 数量。每个都是黄旗——问问解释原因是否能替代硬性规则。
+
+### 原则二：渐进披露
+
+**解决的问题**：上下文窗口浪费、认知过载。
+
+在正确的时机加载正确的信息。三层模型：
+
+| 层级 | 内容 | 预算 | 何时加载 |
+|------|------|------|----------|
+| 触发层（description） | 何时激活 | ~100 词 | 始终在上下文中 |
+| 认知层（SKILL.md body） | 如何思考 | <500 行 | 触发时加载 |
+| 资源层（references/） | 深度细节 | 不限 | 按需加载 |
+
+**诊断信号**：SKILL.md 超过 500 行时，内容放错了层级。将实现细节、检查清单、领域特定知识移到 references/。
+
+**自检**：只用 SKILL.md body（不看 references），AI 能完成 80% 的任务吗？如果不能，关键知识埋在了错误的层级。
+
+### 原则三：信噪比优化
+
+**解决的问题**：重要指令被填充内容稀释。
+
+每句话都必须证明自己存在的必要性。信号 = 改变 AI 行为的信息。噪声 = 消耗上下文却无效果的填充。
+
+**常见噪声模式**：
+- 仪式性语言（"请注意……"、"重要的是……"、"需要强调……"）
+- 不增加新信息的冗余重述
+- 不增加精确度的对冲用词
+
+**精简方法**：删掉一句话，如果行为不变，它就是噪声。
+
+**悖论**：适度冗余是信号——在不同上下文中重复核心原则能强化记忆。区别在于每次重复是否增加了新的上下文。
+
+### 原则四：单一职责
+
+**解决的问题**：触发混淆、维护负担、代码膨胀。
+
+一个 skill，一件事。如果描述 skill 职责时需要用"和"连接两个动作，考虑拆分。
+
+**拆分信号**：
+- 指令超过 500 行
+- 条件分支超过 5 个
+- 无法用"动词+名词"一句话描述
+- AI 频繁选错工具或跳过步骤
+
+**合并条件**：
+- 两个 skill 共享大部分工具和指令
+- 拆分后 handoff 开销超过收益
+
+### 原则五：闭环验证
+
+**解决的问题**：错误在多步骤任务中静默累积。
+
+在关键决策点设计验证环节——不要把所有检查都推迟到最后。
+
+| 验证类型 | 时机 | 示例 |
+|----------|------|------|
+| 微验证 | 每步完成后 | 编译通过？文件存在？ |
+| 阶段验证 | 里程碑后 | 满足阶段目标？ |
+| 终验证 | 任务完成时 | 满足原始需求？ |
+
+**诊断信号**：如果 skill 没有任何验证点，它是开环系统——简单任务可行，复杂任务必不可靠。
+
+### 原则六：复杂度适配
+
+**解决的问题**：简单任务用了重型框架，复杂任务用了轻量指令。
+
+让框架的重量匹配问题的重量：
+
+```
+简单 → 快速路径：直接执行 + 验证
+中等 → 标准路径：规划 → 执行 → 验证
+复杂 → 深度路径：澄清 → 探索 → 规划 → 执行 → 验证
+```
+
+一个 skill 应在内部支持不同复杂度路径，而非强制所有输入走最重的流程。
+
+**诊断信号**：如果一个 5 分钟的任务也要走完整的分析-规划-执行-验证循环，说明 skill 过度设计了。
+
+### 原则七：抗过拟合
+
+**解决的问题**：skill 在测试用例上完美，在真实使用中失败。
+
+写传授推理模式的指令，而非输入-输出映射。如果一个修改只修复了某个特定测试用例，它很可能是过拟合。
+
+**健康的示例**：3-5 个多样化示例，展示*推理过程*而非仅展示最终输出。
+
+**诊断信号**：换一组完全不同的测试输入，skill 能表现一样好吗？如果不能，它过拟合了。
+
+---
+
+## 第三步：重构
+
+基于诊断结果和选定原则，重构 skill。
+
+### 触发层优化（description）
+
+description 决定 skill 是否被激活。同时优化精确率和召回率：
+
+**结构公式**：`[做什么] + [何时触发] + [何时不触发] + [与相邻 skill 的边界]`
+
+**常见修复**：
+- 触发不足 → 增加触发场景、替代措辞、非显式用例
+- 过度触发 → 增加排除条件、与相似 skill 的显式边界
+- 两者皆有 → skill 的职责范围不清——回到单一职责原则
+
+### 认知层优化（SKILL.md body）
+
+**结构优先级**：
+1. 开头声明使命——1-2 句话说明目的和核心理念
+2. 原则先于流程——先建思维框架，再给具体流程
+3. 决策树优于步骤列表——"在此情境下判断 X"优于"按顺序做 1-2-3"
+4. 正面指引与反模式并存——展示什么是对的 AND 什么是错的（及为什么错）
+5. 指向资源层——清晰的"何时阅读什么"指引
+
+**写作风格**：
+- 祈使语气（"分析依赖图"而非"你需要分析依赖图"）
+- 为每条规则解释原因
+- 最小化 ALWAYS/NEVER——尽量用推理来替代
+
+**长度检查**：
+- 理想：200-400 行
+- 上限：500 行
+- 超过 500 行：移内容到 references/
+- 超过 1000 行：skill 职责过于宽泛，考虑拆分
+
+### 资源层优化（references/）
+
+- 按领域/主题组织，而非按功能
+- 每个参考文件应独立可用
+- 大文件（>300 行）包含目录
+- 脚本可以不加载到上下文中直接执行
+
+---
+
+## 第四步：验证
+
+### 快速验证（每次都做）
+
+- [ ] description 清晰传达了何时触发、何时不触发
+- [ ] SKILL.md 在 500 行以内
+- [ ] 无孤立的 references（所有引用都从 SKILL.md 指向）
+- [ ] 核心原则在 SKILL.md 中，未埋在 references 里
+- [ ] ALWAYS/NEVER 数量减少，或每个都附有原因说明
+
+### 深度验证（重大变更时）
+
+- 以"第一次看这个 skill"的视角阅读。3 分钟内能理解意图吗？
+- 脑中推演 2-3 个现实场景。skill 能引导正确行为吗？
+- 回归检查：之前有效的功能是否会被影响？
+
+### 成熟度评估
+
+| 等级 | 特征 | 优化重点 |
+|------|------|----------|
+| L0 草稿 | 能工作但不稳定，需要人工干预 | 触发准确率 + 基本功能 |
+| L1 可用 | 多数场景正确，偶有失误 | 边界情况 + 错误恢复 |
+| L2 可靠 | 稳定、高效、可预测 | Token 效率 + 精简 |
+| L3 优雅 | 正确、简洁、灵活、可组合 | 泛化能力 + 架构简洁 |
+
+---
+
+## 优化纪律
+
+**每次只改一处**：修改触发 OR 认知 OR 资源层。改完验证。不要累积修改。
+
+**读 transcript，不只看输出**：执行过程暴露了最终输出隐藏的浪费和困惑。如果 AI 花了 500 token 在某个本应由 skill 明确的事情上犹豫，那就是优化目标。
+
+**知道何时停止**：开始前定义"足够好"。边际收益递减是真实的——L0→L1 的跃升通常比 L2→L3 更有价值。
+
+---
+
+## 反模式速查
+
+| 反模式 | 症状 | 修复方向 |
+|--------|------|----------|
+| 规则堆砌 | ALWAYS/NEVER 满天飞，>1000 行 | 减少规则，增加解释 |
+| 过拟合 | 测试用例完美，真实使用失败 | 泛化原则，增加示例多样性 |
+| 噪声膨胀 | "请注意"、"重要"等仪式性填充 | 删除后检查行为是否变化 |
+| 抽象过度 | 原则太抽象无法指导行动 | 增加判断标准和边界案例 |
+| 步骤固化 | 对多样化输入用死板的 1-2-3 | 决策树替代步骤列表 |
+| 巨石 Skill | 一个 skill 做所有事 | 按职责拆分 |
+| 缺少闭环 | 执行完不验证 | 在关键节点插入验证 |
+| 批量优化 | 一次改 5 处，不知道哪个生效 | 一次改一处，改完验证 |
+
+---
+
+## 深度参考
+
+按需阅读，不必每次都加载：
+
+- `references/theory-foundations.md` — 每条原则背后的认知科学、哲学和信息论基础。当你想理解原则*为什么*有效（而非仅仅*是什么*）时阅读。
+- `references/quality-checklist.md` — 详细的诊断检查清单、transcript 分析指南和精简方法论。做深度优化时阅读。

package/templates/skills/skill-optimize/references/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Skill(report)"
+    ]
+  }
+}