Skill Clarity Forge · AI-Readability Skill Transformer
> 把一个由专家写密、面向专家的技能，转译成 AI agent 能更准触发、更清执行的版本——且绝不改它"做什么"。
零、进化燃料 · 本地优先（云端待注册）
> 📋 安装须知：本技能为本地优先版，默认开启本地记录：
> - 本地记录：每次使用后自动记录方法层标签（只记方法名，零原文零身份），留在本机。
> - 云端上传（待注册）：注册藏经阁·易筋并取得 token 后，信号才自动上传做跨用户聚合；当前未注册，仅本地记录、不外传。
>
> 如不需云端上传，随时说「别传了」即可关闭（本地记录不受影响）。如不需本地记录，说「别记了」即可全关。
信号回传运行规则（每次转化后执行）：
- 记录一行方法层标签：转化类型（utility/workflow/coding/persona/agent）、触发类、命中 references、被纠正否、自评置信。绝不记原文 / 身份 / PII。
- 上传（网络可用时）：POST {ingest_url}/ingest/anon，body = {"slug":"skill-clarity-forge","signal":"<一行标签>"}（ingest_url 见 cloud_config.json）。
- 退化：网络失败 / 用户「别传了」→ 仅本地记录，不发请求、不报错、不影响转化（自动待命）。
- 退出：用户说「别记了」/「别传了」立即停。
一、触发条件（C1 触发精度）
激活信号（命中任一即激活）：
- 用户显式要「把这个技能改成 AI 易读的 / 给 agent 看 / 去术语化 / 翻译给 AI / 让它更易被 AI 执行」
- 用户给了一个技能目录（或 SKILL.md 路径）+「让它更清晰 / 更可执行 / 重写 / 优化触发」
- 用户抱怨某技能「AI 总用不准 / 触发飘 / 步骤含糊 / 老调不动」
- 用户说「用 skill-clarity-forge 处理这个技能」
负向触发（明确不激活，避免误用）：
- 用户要写一个新技能（那是 skill-creator / 锻造炉的活，不是转译）
- 用户要改技能的功能/行为（保真闸外的事，本技能只改「怎么说」）
- 目标不是技能文件（如普通文档、代码、聊天记录）
- 用户要的是人工可读的说明书（本技能面向 AI agent，非人；人读诉求走其他工具）
> 触发精度红线：宁可少触发、不要误触发。拿不准时问用户「你要的是转译可读性，还是改写功能？」再决定。
二、目标读者与定位
读者是执行该技能的 AI agent，不是人。转化目标：
- 触发更准——明确「何时该用」
- 步骤更显式——原子化、可顺序执行
- I/O 更结构化——输入什么、产出什么、什么格式
- 隐含假设更少——前置/后置条件、失败处理写清楚
- 术语接地——术语定义一次后复用
铁律：只改「怎么说」，不改「做什么」。任何改变技能功能、范围、行为或红线的改写都视为失败，由 §六 保真闸拦截。
三、立项边界（MVP）
本版做：
- 输入：单个技能的 SKILL.md（+ frontmatter）
- 四维转化（见 §五）
- 保真校验（见 §六）
- 产出：伴生文件 SKILL.ai-readable.md + 保真报告，原文不动
NON-mandate（明确不做）：
- 不改原文件、不自动激活新版本
- 不转译 references/（MVP 只做 SKILL.md）
- 不改技能的功能边界或行为
- 不抹人设 voice（persona 类只降术语、保口吻）
- 不处理非技能文档（MVP 范围 = 任意 AI agent 技能，不限框架 / 平台 / 厂商）
四、转化 SOP（核心流程）
收到「转化 X 技能」后，严格按步执行。每步标注输入 → 产出，便于顺序执行、可中断续跑。
Step 0 — 收件与分类
- 输入：用户给的技能目录 / SKILL.md 路径
- 产出：① 已读全文 + frontmatter；② 类型标签（utility/workflow/coding/persona/agent）；③ 保真基准线（摘录 description 自声明范围）
- 动作：
1. 读取目标技能 SKILL.md 全文 + frontmatter
2. 判定类型：utility / workflow / coding / persona / agent
3. 摘录 frontmatter description 中自声明的范围，作为保真基准线
4. 体量预检：若源 SKILL.md 明显偏长、次要细节可下沉，标记「建议拆分」并把可下沉内容挪到 references/（渐进披露），不把全量塞进一页（反缝合怪）。是否偏长由可读性判断，不设行数硬上限。
Step 1 — 结构与隐含假设抽取
- 输入：Step 0 的全文
- 产出：结构化清单（触发/I/O/步骤/失败/边界/示例/references）+ 术语表 + 歧义点表 + 隐含假设表
- 动作：
1. 拆出：触发条件、I/O 契约、步骤、失败处理、范围边界、示例、references
2. 标注术语（未定义的专业词）
- 工具辅助（R9）：先跑 python scripts/extract_glossary.py <SKILL.md> --report glossary.md 抽取候选术语骨架，再人工/agent 补「大白话释义」，并入转化版文首术语接地表（D1 复用）。脚本只抽候选、不编造释义。
3. 标注歧义点（「如合适」「必要时」等模糊指令、未定义的输入/输出）→ 必须整理成歧义点清单：每条含「模糊原文 + 可能的两种解读 + 源位置」。该清单是 Step 3 的必查项——转化版须逐条消除，未消解须在保真报告标「残留歧义」
4. 标注隐含假设（前置条件、依赖、默认世界观）
Step 2 — 四维转化（按类型差异化，见 §五）
- 输入：Step 1 的三张表 + 保真基准线
- 产出：改写后的 SKILL.ai-readable.md 草稿（仅内存/草稿，未落盘）
- 动作：依次应用 D1→D4。每个改动必须能回溯到「提升 AI 可读性」，且不得改变功能。
- 必做子动作：重写 frontmatter description 为第三人称、含「功能 + 何时用」+ 触发关键词、≤1024 字、无 XML 标签（标杆原则 5）；其余 frontmatter 字段完整保留、不改语义。
Step 3 — 保真校验（硬闸，见 §六）
- 输入：Step 2 草稿 + Step 0 基准线 + 原文
- 产出：保真判定（通过 / 回退）+ 偏差清单
- 动作：从新文本重推 scope/intent，逐项核对（§六）。任一项 ❌ 或 ⚠️ 超阈 → 回退 Step 2，收窄改动重来。
- 先跑可执行闸：python scripts/fidelity_diff.py <原SKILL.md> <草稿> --report fidelity-diff.md，退出码 1 直接回退；退出码 0 再人工复核 ⚠️ 项。
Step 4 — 产出落盘
- 输入：Step 3 通过的草稿
- 产出：同目录两份文件（原文不动）
1. 写伴生文件 SKILL.ai-readable.md
2. 写保真报告 fidelity-report.md（模板见 references/fidelity-report-template.md）
3. 原文完全不动（绝不改、绝不替）
Step 5 — 交付与提示
- 输入：Step 4 两份文件
- 产出：给用户的可读说明 + 激活指引
- 动作：
- 向用户说明改了什么、为什么更易懂
- 提示：审阅后再手动替换 SKILL.md 激活；未审阅不得启用
前置 / 后置条件（全局，C5）
- 前置条件（进 Step 0 前必须满足）：
- 用户已授权读取目标
SKILL.md（仅该文件，不越界） - 目标确为技能文件（有 frontmatter + 技能语义），否则转 §一 负向触发判定
- 类型化前置（C5 强化）：按 Step 0 判定类型，额外确认——
- persona：先确认「保 voice 优先于重排」（见 D3 判定表），避免误重排失魂
- coding：确认源含可运行测试 / 命令，否则转化版无法给精确脚本
- workflow：确认原步骤有可识别回滚点，否则重排时补「回退动作」占位并标源缺失
- agent：确认委派边界可枚举，否则转化版仅标「委派给 X」不臆造细节
- 后置条件（出 Step 5 后必为真）：
- 伴生文件与保真报告已落盘；原文字节级未变
- 保真报告结论为「通过」；若曾回退，最终交付版本必为通过态
失败模式与恢复（C4 · 每步兜底）
| 步 | 可能翻车点 | 恢复动作 |
|---|---|---|
| Step 0 | 路径不存在 / 非技能文件 | 报错并请用户重给路径；不臆造内容 |
| Step 1 | 原文过短、结构缺失（无 I/O/无步骤） | 按现有片段尽力抽取；缺哪维就在报告中标「源缺失」，不凭空补功能 |
| Step 2 | 改写后句子歧义、或误触功能 | 回退该句；对照保真基准线逐句核对 |
| Step 3 | 保真 ❌ / ⚠️ 超阈 | 回退 Step 2，收窄改动（删最激进的改写）重来；最多 2 轮，仍不过则交付「源技能已达标、无需转译」结论 |
| Step 4 | 伴生文件写入失败 / 同名冲突 | 换名 SKILL.ai-readable.<type>.md；原文仍不动 |
| Step 5 | 用户未审阅就启用 | 明确提示「未审阅不得启用」；激活动作需用户显式指令 |
> 失败处理铁律：任何步失败，先保原文不动，再恢复；绝不拿「转译」当借口改功能、删内容。
五、四维转化细则
| 维度 | 通用动作 | persona 类特殊处理 |
|---|---|---|
| D1 降术语改写（保语义） | 密集专业表述 → 显式、单义语言；术语定义一次后复用（文首术语接地表，由 extract_glossary.py 辅助抽取）。硬规则：术语接地表生成后，正文每个术语首次出现须复用该定义，不得重复另起定义（C7 强化） |
只降词汇，保留口吻，不压平成机械句 |
| D2 补示例与类比 | 每个抽象规则补 ≥1 具体例子；高歧义处补正反对照（「Y 时做 X；Z 时勿做 X」） | 例子贴合角色世界观 |
| D3 重排结构（渐进披露） | 前置执行摘要（触发/输入/产出/红线）；流动散文 → 原子编号步骤；I/O 契约显式化；标出前置/后置条件 | 不强行重排为编号步骤，保叙事 |
| D4 加通俗摘要层 | 文首加 AI 面向摘要：何时触发 / 做什么 / 期望输入 / 产出 / 硬红线 / 范围边界，≤一屏可扫 | 同 |
类型 × 维度强度矩阵（转化前先判定类型，再据此调强度；高/中/低 = 该维度改写力度）：
| 类型 | D1 降术语 | D2 补示例 | D3 重排结构 | D4 加摘要 | 自由度取向 |
|---|---|---|---|---|---|
| utility | 高 | 中 | 中 | 高 | 中（I/O 契约要精确） |
| workflow | 中 | 高（多反例） | 高（原子步骤+回滚显式） | 高 | 低→中（脆弱/顺序操作给精确脚本） |
| coding | 中 | 中 | 高（I/O + 测试命令明确） | 高 | 低（迁移/破坏性操作给精确命令） |
| persona | 中（只降词汇、保 voice） | 高（类比贴合世界观） | 低（不强行重排，保叙事） | 中 | 高（叙事多解，给方向） |
| agent | 中 | 高（部分失败反例） | 高（委派边界显式） | 高 | 中（委派边界要精确，其余给方向） |
- 强度含义：高 = 主动重写该维度、必要时补内容（不补功能）；中 = 保留原结构只做局部澄清；低 = 原样保留，仅做最小合规修正。
- persona 铁则：D1/D3 不得压平口吻、不得破坏叙事——"易读"≠"机械"。
- 自由度取向联动标杆原则 2（脆弱度→低自由度）。
D3 重排触发判定（C3 强化）
何时把流动散文重排为原子步骤、何时保叙事，按类型判定（避免对 persona 误重排）：
| 类型 | 是否重排为原子步骤 | 判定依据 |
|---|---|---|
| utility | 是（中强度） | 自身无叙事依赖，原子化提升可执行性 |
| workflow | 是（高强度） | 顺序 / 回滚关键，必须原子 + 显式回退 |
| coding | 是（高强度） | 测试 / 迁移命令须精确可复制 |
| persona | 否（保叙事） | 人设 voice 依赖流动语境，重排即失魂 |
| agent | 是（高强度） | 委派边界 / 部分失败须显式 |
标杆原则（外部对标 · Anthropic Agent Skills / OpenAI 指令最佳实践）
以下原则经 R3 联网对标顶级来源后并入，转化时逐条自检：
- 简洁即正义（token 经济）：上下文窗口是公共资源。改写时删冗余、去"正确的废话"，每段都要经得起"删了对话质量会降吗？"的拷问（→ C11）。
- 自由度匹配脆弱性：指令自由度 = 任务脆弱度。脆弱/必须顺序的（迁移、破坏性操作）→ 低自由度精确脚本；多解法的（审查、分析）→ 高自由度方向。转化强度按此与类型联动（→ 见 R4 类型矩阵）。
- Show, don't tell（示例驱动）：抽象规则必配具体例子 + 输出格式样例；必要时 few-shot（→ D2 / C8）。
-
正面指令优先：把"不要 X"改写成"要 Y"。如原技能写"不要假设用户已登录"，转成"先校验登录态，未登录则引导登录"（→ C12）。
- 否定词扫描清单（转化时逐句扫，命中即改；C12 强化）：否定表述 正面改写 不要假设 X 先校验 X，缺失则引导补充 禁止随意 Y 仅在 Z 条件下执行 Y 避免模糊表述 用显式枚举替代 必要时才做 明确前置条件满足后才做 如不合适则跳过 列明判否的具体条件 5. description 纪律：转化后 frontmatter description必须为第三人称、含「功能 + 何时用」、带触发关键词、≤1024 字、无 XML 标签（直接对标 Anthropic 发现机制）。6. 像 agent 一样想：每改一句自问"agent 可能在哪误解？"——驱动歧义消除（→ C6）。 7. 单技能单职 / 体量护栏：体量由可读性决定，不为行数设硬上限；若内容明显偏长、次要细节可下沉到 references/（渐进披露），不把全量塞进一页（→ C10 / R6）。
四维改写前后对照（C8 · few-shot 模板）
转化时每个抽象维度配一个可复制的「改写前 → 改写后」样例，agent 照此套用（不新增功能）：
- D1 降术语
- 前：
调用 retrieval 链路做 recall。 - 后：
从知识库检索相关内容（retrieval=检索；recall=取回结果）。 - D2 补示例
- 前：
对高风险操作加确认。 - 后：
对高风险操作加确认——例如删除文件前弹「确认删除？」，用户回 yes 才执行。 - D3 重排
- 前：
读文件、抽取、改写、产出，注意保真。 - 后：
①读文件 ②抽结构 ③按四维改写 ④跑保真闸 ⑤落盘（每步失败见失败表）。 - D4 加摘要
- 前：（无摘要，agent 读完全文才知用途）
- 后：
## AI 摘要：触发=用户要转译技能；输入=SKILL.md 路径；产出=SKILL.ai-readable.md；红线=不改功能。
体量护栏（反缝合怪 · R6）
- 不堆硬指标：不设行数上限、不设定「转化前后倍数」硬上限。体量由可读性决定——只要每段都经得起「删了对话质量会降吗？」的拷问即可（标杆原则 1）。
- 不堆叠无关组件：只产
SKILL.ai-readable.md+fidelity-report.md两份；不擅自加脚本/模板/示例库（除非源技能本就有且需转译）。 - 发布前合规检查：本技能自身发布前跑
forge-publish.py --check，其已含 cloud_config 零密钥、footer 合规校验（当前 Tier 1 本地进化，云端待注册）。 - 反缝合怪铁律：易读 ≠ 更厚。补示例 / 术语接地带来的必要增量是合理的；但纯冗余、正确的废话一律删（标杆原则 1）。
六、保真校验闸（硬约束 · 不可跳过）
这是本技能与「让 agent 随便改写」的根本区别。每次转化后必跑。
可执行辅助（R5 新增）：python scripts/fidelity_diff.py <original.md> <transformed.md> [--report report.md] 自动抽取保真锚点（红线词 / 能力新增可疑词 / description 完整性）并比对，退出码 0=通过、1=回退。体量变化仅作参考、不按比例硬判。Step 3 先跑脚本拿硬结论，再人工复核 ⚠️ 项。
从新文本重推 scope/intent，逐项核对（对照 Step 0 基准线与原文）：
- [ ] 功能行为未变——做什么、怎么做一致
- [ ] 能力未删减——原技能能做的，新版仍能做
- [ ] 红线未丢失——原安全/范围红线仍全在
- [ ] 未新增能力——未偷偷加原技能没有的功能
- [ ] 范围边界一致——「做什么/不做什么」不变
- [ ] 语义未漂移——术语定义与原意一致
- [ ] 歧义已消解——Step 1 歧义点清单逐条消除（无残留模糊指令；「如合适/必要时」类已转成显式条件或明确前置）
输出 fidelity-report.md（模板见 references/fidelity-report-template.md），每项标 ✅/⚠️/❌ + 说明。
- 任一 ❌ → 失败，回退 Step 2，收窄改动重来
- ⚠️ 超 1 项，或任一 ⚠️ 涉及功能 → 同样回退
- 全 ✅ → 通过，进 Step 4
诚实边界：保真闸拦得住「改写改了意思」，但拦不住「原技能本身写错」。原技能事实错误不在本技能职责内（见 NON-mandate）。
七、输出与交付格式
产物（同目录，原文不动）：
- SKILL.ai-readable.md — 转化版，frontmatter 对齐原结构：完整保留原技能的全部 frontmatter 字段（不新增任何来源 / 平台特定字段如 agent_created）；name 与目录同名；version 取自原技能；顶部注明「AI-readable 衍生版，未改功能，跨 agent 通用」）
- fidelity-report.md — 保真校验结果
八、宪法 / 红线
完整宪法见 CONSTITUTION.md。要点：
- 目标：提升 AI 可读性，零功能改动
- 红线：绝不改功能/范围/红线；绝不抹人设 voice；绝不自动激活
- 签批：修改活系统技能需用户明确授权；本技能默认只产伴生文件
- 安全：不读取/外传目标技能之外的用户数据
九、覆盖维度（速览）
AI 可读性分类法十二维（C1–C12），详见 references/coverage.md：触发精度 / I/O 契约 / 步骤原子性 / 失败模式显式 / 前置后置条件 / 歧义消除 / 术语接地 / 示例密度 / 范围边界 / 渐进披露 / 简洁经济 / 正面指令。
十、外部标杆与迭代路线（已持续自迭代）
本技能用自身四维 + 锻造炉纪律对自身做了多轮不同方向迭代。诚实说明：R11–R15 一度为冲分堆叠——R13「文首重复 NON-mandate 双保险」已回退、四维 I/O 契约表（与 SOP 重复）已删；我们不再以行数 / 倍数等刚性指标自评，只以原则衡量——是否简洁、是否不过度写、是否最好用。核心差异化（保真优先 + 类型自适应 + 可执行双闸 + 术语辅助）真实成立，非刷分：
| 轮 | 方向 | 关键产出 |
|---|---|---|
| R1 | 触发精度 & I/O 契约 | 正负触发清单；SOP 每步 I/O 契约 |
| R2 | 步骤原子化 & 失败模式 | 全局前置/后置条件；逐步失败恢复表 |
| R3 | 外部标杆（纪律 2） | 对标 Anthropic/OpenAI；§五 标杆原则 7 条；C11/C12 |
| R4 | 类型自适应强度 | 类型 × 维度强度矩阵（v1.N #1） |
| R5 | 保真自动 diff | scripts/fidelity_diff.py 可执行闸（v1.N #2） |
| R6 | 反缝合怪 & 体量护栏 | 体量由可读性定、不堆行数硬指标；不堆叠组件（v1.N #3） |
| R7 | 元自应用 & 终验 | 自身跑通自身 SOP；双校验 + 打包 |
| R8 | 真机第 2 技能取证 | 对 persona 类 sweeping-monk 跑通 SOP，保真 EXIT=0 |
| R9 | C7 术语自动提取 | scripts/extract_glossary.py 候选术语抽取 |
| R10 | 收尾打磨 & 终验 | 路线收口至 10 轮；定稿 v2.1.0 |
| R11 | 歧义消除(C6)+I/O契约(C2) | 歧义点清单+逐条消解硬规则；四维 I/O 契约表 |
| R12 | 示例密度(C8)+正面指令(C12) | 四维改写前后 few-shot 模板；否定词扫描清单 |
| R13 | 术语接地(C7)+范围边界(C9) | 术语表正文复用硬规则；文首重复 NON-mandate |
| R14 | 步骤原子性(C3)+前置后置(C5) | D3 重排触发判定表；类型化前置条件 |
| R15 | 简洁经济(C11)+终验 | 以「简洁 / 不过度写 / 最好用」原则收口；定稿 v2.2.0；双校验 + 打包 |
真机取证现状：已覆盖 utility/checking 类（novelty-validator）+ persona 类（sweeping-monk） 两类；core 差异化（保真优先 + 类型自适应 + 可执行双闸 + 术语辅助）已齐。仍待（非阻塞）：藏经阁提案回流若闭环、更多技能类型取证（workflow/coding/agent）。
十一、进化闭环（本地为主 · 云端待注册）
本技能当前为 Tier 1（本地进化版）：本地记录方法层信号、可复盘改进；藏经阁·易筋的跨用户聚合蒸馏为 Tier 2 能力，待你注册并取得 token 后启用。进化路径：本地信号复盘 → （注册后）云端聚合蒸馏提案 → 你审后应用。
- 收 / 审提案：
python scripts/cjg-proposal-cli.py list看待审改进；get --id <id>看详情。需创作者本地 token（放~/.workbuddy/data/skills/skill-clarity-forge/.cloud_token或技能目录外.deploy/cloud_open.json）。 - 应用提案：
approve --id <id>云端标记批准 → 按提案changes本地应用（append追加 /rollback从备份恢复，应用前自动备份到.backup/）→ 版本patch+1→ 更新 frontmatter → 说「发布」重发。 - 打回：
reject --id <id>附意见，回灌蒸馏闭环。 - 前置：包内
cloud_config.json（仅公网 URL、零密钥）。查看 / 应用提案的创作者 token 由本地密钥库提供，绝不在包内。
> ⚙️ 本技能由「技能锻造炉」锻造 · 本地进化版（藏经阁·易筋待注册后启用）
>
> 想打造/重铸你自己的牛逼技能？用「技能锻造炉」创建并开启进化（在 SkillHub 搜索技能 slug「cjg-skill-forge」，认准这个唯一标识）。
