Skill Fix

P0 铁律 + [CONTEXT]（Standard 18/21 — frontmatter 后 L7）

[CONTEXT] skill-fix = 技能自我修复基础设施。上游：接收 skill 异常信号（执行偏移/报错/质量不达标）。下游：输出修复后 skill 文件 + 诊断/修复报告。只修改 skill 定义（SKILL.md/config/references/*），不直接执行 skill 逻辑。修改任何文件前必须获用户明确授权。

Standard 27 禁止虚构数据（P0）：步骤跳过/失败时禁止虚构兜底，必须打回重跑前置步骤。

反虚构铁律（P0）：无 Read 输出声称"文件内容是 XXX"=P0 伪造阅读 / 无 Bash 输出声称"命令返回 XXX"=P0 伪造执行 / 无日志声称"用了 XXX 模型"=P0 伪造执行记录 / 无 workflow state 声称"Phase 失败"=P0 伪造状态 / 基于 frontmatter 声明推断实际执行=P0 违规（C5）。

Skill 修改授权铁律（P0 — 覆盖一切）：执行 skill ≠ 修改 skill。执行只需读取，修改必须逐项授权。写入前 Read → 展示 diff → 用户确认 → 写入。用户未明确授权 = 禁止。

证据要求：每个结论附带 evidence（path/size/mtime/sha256）。不确定时说"不确定"，禁止推测。 更多 P0：references/anti-fabrication.md、references/fabrication-risk-detection.md

横向对标 + I/O 契约 + 可变参数真源（Standard 10/20/2）

统一术语：审计=系统性扫描找缺陷 / 诊断=针对具体问题根因分析 / 修复=最小改动消除缺陷 / 验证=基于证据确认修复生效。后续段落统一用此 4 词。

1. 横向对标（Standard 20）

skill-fix 相对优势：审计能力最强 / 42+ 标准 / config 外置 / [CONTEXT] + I/O 契约 / 反虚构铁律。

2. I/O 契约（Standard 2/7） + Goal 模式注入（Standard 43-46）

3. 可变参数真源（Standard 10）

阈值/token/路径/严重程度/工作流 → @config.json。触发时 Read 一次。详见 references/externalized-config.md。

核心原则

1. 先报告再修复 — 诊断报告经用户确认后才执行修复
2. task() 追踪 — 修复全程用 TaskCreate/TaskUpdate/TaskList 追踪
3. 根因分析优先 — 不只修表面错误
4. 最小改动 — 只改必要的部分
5. 证据驱动 — 每个结论必须有实际证据
6. 禁止模糊语言 — 指令必须明确
7. 用户意图优先 — 不扩大范围
8. 安全准则注入 — 修复时检查目标 skill 是否含安全准则
9. 先计划后执行 — 制定修复计划，用户确认后再动手

安全准则要求

每个 skill 必须含安全准则（≤10 行）：

• [P0] 修改前必须 Read 确认当前内容
• [P0] 禁止 rm -rf 删除他人数据目录
• [P1] 禁止 curl/wget | bash
• [P1] 写入前展示完整内容，等待确认
• [P2] 不修改用户未要求的文件
• [P0] 不修改 .gitignore/.editorconfig 等除非用户明确要求

Karpathy 铁律 + 模型路由 + 步骤标注

Karpathy 4 条：P1 先想 / P2 最小 / P3 手术刀 / P4 闭环。详情 references/karpathy-laws.md 模型路由：R1 严格遵循 frontmatter / R2 禁止增删 / R3 临时替代仅限单次。详情 references/model-routing.md 步骤标注：必选·不可跳过 / 必选·条件跳过 / 可选·建议 / 可选·按需。详情 references/mandatory-annotation.md

触发条件（对齐 config.json#triggers）

完整 11 触发词场景标注见 @config.json#triggers。

Goal 模式注入（Standard 43-46）

触发条件：诊断报告发现目标 skill 缺失 Goal 模式要素（Standard 43-46 任一不通过）→ 自动进入 Goal 模式注入流程。

目的：让所有技能执行时都有明确目标和验证机制，不再"好像完成了"。

注入流程（6 步）：

注入位置（标准化）：在目标 skill 的 SKILL.md 中追加：

1. frontmatter description：追加"| 目标模式 /goal 目标驱动"
2. 触发条件：追加"| 目标类 | /goal / 目标驱动 / 验收标准 / 验证机制"
3. 执行流程：追加 Goal 6 步流程段
4. 输出结构：追加 plans/task-{id}/ 目录说明

详细模板：references/goal-mode-injection.md 合规检查清单：references/goal-mode-audit.md

Goal 质量铁律（Standard 47-52）— 抗偏移强制

核心问题：模糊的 Goal + 模糊的 VC = 执行偏移。"优化/改善/提升"等动词 + "合理/基本/大致"等判定词 = 终验失效。

Standard 47：Goal 语句清晰性强制（P0）

禁止动词（无具体产出）：优化 / 改善 / 增强 / 提升 / 改进 / 完善 / 加强 / 促进

必须包含：交付物名词 + 交付形式 + 交付标准

✅ 正确: **Goal**: 给定查询，返回符合 schema.json 的多源检索结果 + 验证证据。
❌ 错误: **Goal**: 优化调研流程，提升结果质量。

审计命令：grep -n 'Goal:' SKILL.md | grep -E '优化|改善|提升|改进|完善' → 命中 = P0 违规。

Standard 48：VC 客观性强制（P0）

禁止词（模糊判定）：合理 / 基本 / 大约 / 应该 / 大致 / 差不多 / 足够 / 适当 / 良好 / 优秀

必须包含：判定动作 + 判定对象 + 判定标准

✅ 正确: - [ ] VC-1: 结果含 _channel_attempts[] 字段（jq '. | length > 0' 校验）
❌ 错误: - [ ] VC-1: 调研结果基本完整合理

审计命令：逐条 VC grep 禁止词列表，命中 = P0 违规。

Standard 49：Phase 互斥性强制（P1）

每个 Phase 必须有独占产出，Phase N 的 Input = Phase N-1 的 Output。

Phase 1 判定类型 → 产出: routing_decision.json
Phase 2 检索执行 → 输入: routing_decision.json → 产出: _channel_attempts[]
Phase 3 组装输出 → 输入: _channel_attempts[] → 产出: schema-compliant JSON

检测方法：grep 各 Phase 产出文件名，出现 ≥2 次 = 职责重叠。

Standard 50：VC 冲突检测（P0）

VC 必须：不互斥 / 不冗余 / 不冲突。

审计命令：对比所有 VC 的判定对象和判定标准，标记矛盾。

Standard 51：证据路径强制（P1）

每条 VC 必须标注证据来源（文件路径 / 命令 / 输出）。

✅ - [ ] VC-1: _channel_attempts[] 非空（路径: {task_plan.md} Phase 2 节）
✅ - [ ] VC-2: schema 校验通过（命令: jq '.' < output.json > /dev/null 2>&1）
❌ - [ ] VC-1: 结果看起来不错

Standard 52：技能目标与现有职责对齐（P1）

注入的 Goal 必须与原 skill 核心功能一致，不得引入新职责。

原 skill 职责: 多源信息检索（搜索 + 提取 + 组装）
✅ 对齐 Goal: 返回符合 schema 的多源检索结果 + 验证证据
❌ 偏离 Goal: 优化搜索策略、改进结果排序、提升用户体验（引入新职责）

检测方法：对比 Goal 动词/名词与 skill 原有 I/O 契约 + 决策路由，出现 3 个以上新名词 = 偏离。

Goal 注入后质量门控（必做）

注入完成后，skill-fix 必须执行以下检查：

1. 逐条 VC 主观词扫描：grep -n '合理\|基本\|大致\|应该\|大约\|足够' target-skill/SKILL.md → 命中 = P0 回退
2. Goal 动词扫描：grep -n 'Goal:' target-skill/SKILL.md | grep -E '优化|改善|提升|改进|完善' → 命中 = P0 回退
3. Phase 职责重叠扫描：对比各 Phase 产出文件名，重叠 ≥2 次 = P1 警告
4. VC 冲突扫描：人工比对 VC 间无互斥/冗余/逻辑冲突
5. 技能目标对齐扫描：确认 Goal 未引入原 skill 职责外的新功能

任一检查 FAIL → 回退注入内容 → 重新设计 Goal/VC → 再次注入。

三阶段执行概述 + 分类 Gate

阶段 1：诊断报告 — 调研(R1-R8) → 证据完整性检查(C1-C5) → 36+2 标准审计 → 根因分析 阶段 2：用户确认 — 展示诊断报告和修复计划 → 修改范围 Gate 校验 阶段 3：修复实施 — 按优先级修复 → 完整性反思(Q1-Q9) → 参数同步(Q7-Q9) 链式技能专项 — 检测到管线编排类 skill 缺陷（缺失 .comet.yaml 字段、预设错误、路由断裂、Node Contract 缺失）→ 调用 Skill(skill='skill-chain-generator') 生成修复后的 chain YAML 并重新生成 SKILL.md → 将修复后的 SKILL.md 回传验证。

技能类型分类（Standard 1.38）

按类型应用标准摘要

36 标准索引表

强制约束

• frontmatter 是 truth source，scripts 禁止覆盖
• SKILL.md 核心 ≤5K chars，超标内容拆分 references/
• 所有约束在开头一次性声明（单次加载原则）
• 本文件 2026-07-16 重新结构化，目标 ≤400 行

Task 执行强化（Standard 1 Enhancement — 2026-07-16）

核心解决：skill 执行过程中最常见的偏移原因不是模型"不听话"，而是缺乏结构化的 task 追踪和数据流约束。

强制要求：

1. Task 全生命周期追踪 — 每个 skill 执行时必须创建 task 树，每个步骤开始前 in_progress、完成后 completed
2. 稳定数据流契约 — 每个任务有 Input/Output/验证/失败回滚 4 元组，前任务产出 = 后任务输入
3. 偏移检测机制 — 步骤跳过/重复/串并行/范围偏移/模型降级，5 类偏移自动检测

详见 references/task-tracking-enhancement.md。

⚠️ 子代理 Skill() 访问限制 — 强制要求（Standard 39）

子代理（通过 Agent() 派发）不拥有 Skill() 工具。 主进程调用 Skill() 正常，但子代理收到 No such tool available: Skill 错误。这是结构性限制，不是 bug。

审计检查项

当你审计一个 skill 时，必须检查该 skill 是否在子代理 prompt 中直接要求了 Skill() 调用：

风险模式（P1）：SKILL.md 或 Agent prompt 中写道"调用 Skill(skill=\"other-skill\") 执行 X"，但执行该步骤的是子代理 → 调用必然失败，流程 HARD_BLOCK。

检测方法：

1. 读取被审计 skill 的 SKILL.md
2. 搜索 Skill( 出现在 prompt/指令段落中（非主进程执行路径）
3. 检查该步骤是否通过 Agent(subagent_type=...) 派发执行
4. 如果两者同时存在 → P1 违规

修复方案：双轨机制

内联模板（小 skill fallback）

当 skill-fix 检测到子代理 prompt 中要求了 Skill() 调用时，修复如下：

# ❌ 错误 — 子代理无法调用 Skill()
Agent(subagent_type="some-agent", prompt="""
...
执行 X 步骤，调用 Skill("small-skill", "arg1 arg2")
...
""")

# ✅ 正确 — 主进程派发时内联 skill 指令
Agent(subagent_type="some-agent", prompt="""
## 执行 X 步骤

直接按以下规则执行（已内联 small-skill 的核心逻辑）：

> 来自 .claude/skills/small-skill/SKILL.md：
> [关键指令段落...]

参数：arg1={arg1}, arg2={arg2}
输出：标准产出文件路径
""")

路径引用模板（参考用）

当子代理需要了解另一个 skill 的规则/约束时：

# ✅ 正确 — prompt 中包含完整 skill 文件路径
Agent(subagent_type="auditor", prompt="""
## 质量审查规则

审查时请严格遵循以下规范的约束：
- 禁止模式：@/home/terry/.claude/skills/banned-patterns/SKILL.md
- 标注要求：@/home/terry/.claude/skills/mandatory-annotation/SKILL.md

审查产出按 {output_spec} 格式输出。
""")

不可接受的 workaround

修复报告必含内容

skill-fix 在报告中发现此问题时的格式：

## 子代理 Skill() 调用风险（Standard 39）
- **严重程度**: P1
- **位置**: {target-skill}/SKILL.md L{line}
- **问题**: 子代理 prompt 中要求调用 Skill(\"{skill-name}\")，但子代理无 Skill() 工具
- **修复方案**: {内联指令 / 改为主进程执行 / 路径引用}
- **验证**: 删除 Skill() 调用后子代理 prompt 中包含完整执行指令

references/ 索引（按需 Read）