AI易读转化器

一个反复出现的坑

你手写的技能在你自己脑子里是清晰的：什么时候该用、先做什么、输出放哪儿。但对 agent 来说，这些信息要么散落在散文里，要么被术语和「必要时」「如合适」这类措辞盖住。结果是触发飘、步骤含糊、agent 反复调不动。

skill-clarity-forge 针对的正是这个问题——它不是帮你写新技能，而是把已有技能从「人读版本」转译成「agent 可执行版本」。

它怎么做

核心是一条四维改写流水线，每一步都要求能回溯到「提升可读性」，而不是随手重写：

• D1 降术语：专业表述改写为显式单义语言，术语在文首定义一次后正文复用，脚本 scripts/extract_glossary.py 负责抽候选骨架，释义由人补。
• D2 补示例：每个抽象规则配至少一个具体例子，高歧义处补正反对照。
• D3 重排结构：把流动散文拆成原子编号步骤，I/O 契约显式化。但 persona 类技能不强行重排——人设 voice 依赖语境，重排即失魂。
• D4 加摘要：文首加一屏可扫的 AI 摘要，包含触发条件、输入输出、硬红线。

改写强度不是一刀切。utility、workflow、coding、agent、persona 五类各有强度矩阵：workflow 和 coding 给高重排 + 精确回退动作，persona 则保叙事、只降词汇。

最关键的是保真闸。每次转化后跑 scripts/fidelity_diff.py，从新文本重推 scope 和 intent，逐项核对功能行为、能力删减、红线丢失、能力新增、语义漂移、歧义残留。任一项不通过就回退收窄改动，最多两轮。产物是伴生文件 SKILL.ai-readable.md 加一份保真报告，原文件字节级不动。

边界要看清

• 它不改写功能。只改「怎么说」，不改「做什么」。想加新能力或改行为，这个技能帮不了你。
• 它不写新技能。从零创建是另一个工具的事。
• MVP 版本只转译 SKILL.md 本体，references/ 目录不在范围内。
• 保真闸拦得住「改写改了意思」，拦不住「原技能本身就写错」——原技能的事实错误不在职责内。
• 转化版默认不激活，需要你审阅后手动替换。