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	体积	标准数	config.json	反虚构铁律	触发场景
skill-fix（本）	162 行	36+2	✅ 589 行 16 字段	✅ P0 区块	诊断修复
skill-creator	485 行	无显式	缺失	无	新建 skill
skill-evolve	63 行	极简	缺失	无	增量优化

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

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

阶段	输入	输出	示例
触发	skill 异常信号（执行偏移/报错/质量不达标）	任务分类（修复/审计/优化）	"fix this skill"
诊断	skill 文件路径 + 异常描述	诊断报告（含 evidence）	SKILL.md: 162行, P0 命中 3 条
修复	诊断报告 + 用户授权	修改后 skill 文件（diff）	SKILL.md L21-L27 重构
验证	修复后文件 + 标准集	验证报告（通过/未通过）	"Standard 6 ✅ 162行 ≤ 400"
Goal 注入	诊断报告含 Goal 缺失 + 用户授权	注入 Goal 模式（Goal 语句 + VC + Phase 验收）	references/goal-mode-injection.md

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）

类别	触发词	场景
修复类	fix skill / skill not working / agent output unstable / 技能修复 / 诊断技能	skill 执行失败/报错/偏移
容量类	file too large / 描述太长 / 瘦身 description	文件超阈或 description 膨胀
优化类	optimize description / reduce skill context cost / context pollution	上下文污染/触发精度差
合规类	（隐式）合规性审计、权限越界、缺少 task 追踪	用户主动要求审计或发现违规
链式技能	chain skill	管线编排类 skill 缺陷（缺失状态字段/预设错误/路由异常）→ 调用 skill-chain-generator 修复

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

---

Goal 模式注入（Standard 43-46）

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

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

注入流程（6 步）：

步骤	动作	产出
Step 1	目标解析	Goal 语句（1 句）+ Verification Contract（≥5 条 VC）
Step 2	拆 Phase	3-7 个可完成 Phase，每个含目标 + 验收标准
Step 3	每 Phase 验收	≥2 条 verifiable check，编号 V-N.M
Step 4	执行 gated	禁止 phase 跳步，验证通过才进下一 phase
Step 5	Phase 间验证	当前 phase 全 PASS → 进下一 phase
Step 6	终验（Goal Gate）	Check-All 清单 + 证据 → COMPLETE/PARTIAL/BLOCKED

注入位置（标准化）：在目标 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-1: A>B, VC-2: A<B	合并或删除冲突 VC
冗余	VC-1: 结果非空, VC-2: results[] 非空	删除冗余，保留 1 条
逻辑冲突	VC-1: ≤60min, VC-2: ≥3次重试 × 120s	调整阈值使两者可同时满足

审计命令：对比所有 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）

类型	特征	适用标准
管线编排类	多阶段/子代理/批量	1-36 全部
工具/数据类	CLI/API/数据处理	2/5/6/8/9/15/25/34

按类型应用标准摘要

标准	管线编排	工具/数据
1 TaskCreate	✅	❌
2 I/O 契约	✅	✅
4 Agent 五段式	✅	❌
6 工作目录	✅	✅
8 自我纠正	✅	❌
9 配置外置	✅	❌
11 子代理拆分	✅	❌
12 专用 Agent	✅	❌
15 输出模板	✅	✅
25 触发词正交	✅	✅
34 模型路由	✅	✅

---

36 标准索引表

#	名称	P	摘要	详情
1	task() 追踪	P2	TaskCreate 模板 + 父子层级	references/quality-standards.md §1
2	I/O 契约	P2	Input + Output + Example	references/quality-standards.md §2
3	中断感知	P2	评估→保留→重排→通知	references/quality-standards.md §3
4	工具调用合规	P1	Agent 五段式 + Skill()	references/quality-standards.md §4
5	上下文管理	P2	References + Progressive	references/quality-standards.md §5
6	文件大小	P2	≤5K chars，拆分到 references/	本文件
7	I/O 三元组	P2	Purpose/Input/Output/Example	references/io-contract-spec.md
8	工作目录	P1	PROJECT_ROOT + 禁止 cwd	references/stable-workdir.md
9	反虚构	P0	evidence + verify	references/anti-fabrication.md
10	配置外置	P1	阈值/token → config.json	references/externalized-config.md
11	示例驱动	P1	正确/错误示例	references/quality-standards.md §11
12	子代理拆分	P1	多阶段拆分子代理	references/subagent-split-enforcement.md
13	专用 Agent	P1	Phase→Agent 映射	references/designated-agent-audit.md
14	Task 描述	P2	量化+产出+验证	references/task-description-spec.md
15	输出模板	P1	具体格式模板	references/repair-templates.md
16	防幻觉	P1	证据+验证+负结果+置信度	references/repair-templates.md
17	禁止权威幻觉	P1	无"资深/总是正确"	references/quality-standards.md §17
18	指令优先级	P0	P0 在 frontmatter+3 行	本文件 L7
19	单次加载	P0	约束在开头一次性声明	本文件
20	横向对标	P1	对标 ≥2 peer skills	本文件
21	[CONTEXT]	P1	管线位置说明	本文件 L7
22	负面+替代	P1	❌ 后跟正确做法	贯穿全文
23	约束分级	P1	P0/P1/P2/P3	贯穿全文
24	少样本示例	P1	真实数据示例	references/repair-templates.md
25	触发词正交	P1	不重叠误触发	references/trigger-orthogonality-audit.md
26	工具即 Prompt	P1	工具接口=prompt 精度	references/tool-disclosure.md
27	自我纠正	P0	前置检查+禁止虚构+回滚	references/fabrication-risk-detection.md
28	外部知识锚定	P1	事实可追溯	references/quality-standards.md §28
29	分层职责	P2	检测与修复解耦	references/quality-standards.md §29
30	Prompt Chaining	P2	Step→Gate→Step	references/quality-standards.md §30
31	动态上下文注入	P2	! 语法注入	references/quality-standards.md §31
32	结构化反思	P2	5 字段 schema	references/quality-standards.md §32
33	零侵入改进	P2	优先外部化配置	references/quality-standards.md §33
34	模型路由一致	P1	声明模型等级	references/model-routing.md
35	反模式库	P3	对照历史陷阱	references/quality-standards.md §35
36	盲测对比	P3	≥3 场景盲测	references/quality-standards.md §36
37	虚构风险检测	P1	Agent 输出虚构/跳过/绕过	references/fabrication-risk-detection.md
38	工具清单披露	P1	前 15% 列出全部工具	references/tool-disclosure.md
39	子代理 Skill() 降级路径	P1	子代理无 Skill() 工具时的 fallback	references/fabrication-risk-detection.md §RP5
40	frontmatter 一致性	P1	tools/model/description 与正文约束无矛盾	references/frontmatter-consistency.md
41	配置 Schema 完整性	P0	路径确定性 + Schema 文档 + 加载无静默失败	references/config-schema-integrity.md
42	质量 > 速度 P0 铁律	P0	bypass 标志受控 + 中断主动解决 + 禁模型降级	references/quality-over-speed.md
43	Goal 语句定义	P1	每 skill 开头有 1 句 Goal 语句	references/goal-mode-audit.md
44	Verification Contract	P1	≥5 条 VC 客观判定标准	references/goal-mode-audit.md
45	Phase 验收机制	P1	每 phase ≥2 条 verifiable check	references/goal-mode-audit.md
46	/goal 自动触发	P2	description 含"目标/确保/验证"触发词	references/goal-mode-audit.md
47	Goal 语句清晰性强制	P0	Goal 必须含具体交付物+交付形式+交付标准	references/goal-quality-enforcement.md
48	VC 客观性强制	P0	每条 VC 必须有判定动作+对象+标准，禁模糊词	references/goal-quality-enforcement.md
49	Phase 互斥性强制	P1	Phase 无职责重叠，N 输入 = N-1 输出	references/goal-quality-enforcement.md
50	VC 冲突检测	P0	VC 无互斥/冗余/逻辑冲突	references/goal-quality-enforcement.md
51	证据路径强制	P1	每条 VC 标注证据文件/命令	references/goal-quality-enforcement.md
52	技能目标与现有职责对齐	P1	Goal 不改变原 skill 核心功能	references/goal-quality-enforcement.md

---

强制约束

• 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 / 简单 skill	prompt 中内联 skill 核心指令 — 把 skill 的执行逻辑直接写入子代理 prompt	见下方"内联模板"
子代理需调用大 skill / 复杂 skill	建议回主进程 — 该步骤不由子代理执行，由 orchestrator 在主进程通过 Skill() 调用	修改 execution flow
子代理需要参考 skill 的规范	prompt 中包含文件路径引用 — @.claude/skills/{skill-name}/SKILL.md 或完整绝对路径	见下方"路径引用模板"

内联模板（小 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()"	虚构执行记录，Standard 9 违规
要求子代理"返回 Skill() 调用命令让主进程执行"	手 off 协议未定义，流程断裂
忽略 Skill() 调用让子代理仅凭 prompt 自行处理	无 skill 规范约束，质量不可控

修复报告必含内容

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

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

references/ 索引（按需 Read）

文档	用途
anti-fabrication.md	反虚构铁律来源
completeness-reflection.md	多文件修改完整性反思
cross-skill-audit.md	跨 Skill 脚本调用审计
description-optimization.md	description 字段独立优化流程
designated-agent-audit.md	指定 Agent 审计
error-patterns.md	常见错误模式库
externalized-config.md	config.json 外置规范
goal-mode-injection.md	Goal 模式注入模板（Step 1-6）
goal-mode-audit.md	Goal 模式合规审计检查清单
goal-quality-enforcement.md	Goal 质量铁律（Standard 47-52）详细规范
fabrication-risk-detection.md	Standard 37 虚构风险检测
io-contract-spec.md	I/O 契约详细规范
karpathy-laws.md	Karpathy 4 条铁律
mandatory-annotation.md	步骤强制标注
model-routing.md	模型路由详细
param-impact-scan.md	参数影响分析与同步
quality-standards.md	36 标准详情
repair-templates.md	诊断/修复报告模板
stable-workdir.md	工作目录稳定协议
standards-15-36-detail.md	Standards 15-36 详细
subagent-skill-call-audit.md	子代理 Skill() 调用审计 — 静默失败检测 + 路径引用修复
subagent-split-enforcement.md	子代理拆分强制
task-description-spec.md	Task 描述规范
task-tracking-enhancement.md	Task 追踪强化（已链 L183）
tool-disclosure.md	Standard 38 工具披露
trigger-orthogonality-audit.md	Standard 25 触发词正交化