把『基于 URL 写一篇博文』这条 prompt 救回来：一个 Claude Skill 的设计、打造与三轮评测实录

如果你在用 Claude（或任何 LLM）写过技术博文，应该熟悉这种沮丧——

你给它一句"基于 https://xxx.com，写一篇博文，图文并茂"，它给你一篇看上去什么都对、读完什么都没记住的 AI 百科。配图只有一张封面，结构是干巴巴的"是什么 / 为什么 / 怎么用"，论点是复述原文的一个稍微改写版本，发出去基本没人转。

你换了几个模型、加了几句"请深入分析、要有洞察"，效果略好但仍不稳。问题不在模型——问题在 prompt 漏掉了太多信号。

prompt-optimizer 是一个为这个高频失败模式量身定做的 Claude Skill。它不是通用 prompt 优化器，只服务一种场景：用户给一个 URL / 一份资料 / 一个主题，让 LLM 写一篇博客发表级别的图文长文。这种需求的失败模式高度集中——所以可以按一份固定的"维度清单"去补。

本文做三件事：

1. 打造过程：从一次糟糕的写作经验讲起，拆开它从概念构思到定型上线的 4 个阶段、每个阶段的关键决策
2. 设计部分：拆开它的 5 维度心智模型与 5 步工作流，讲清楚"它怎么把模糊 prompt 变成可执行的深度 prompt"
3. 评测部分：把我刚做完的一份双轨评测（5 case 质量评测 + 20 query 三轮触发评测）的真实数据贴给你看——包括 F1 怎么从 0.90 推到 1.00、然后100% 之后还能怎么继续进步

提前说一个反常识：分数停在 100% 之后还能继续改 skill——这次实验的最后一轮，分数没变，但 skill 变得更稳了。怎么做到的、为什么值得做，文章后半段会拆开讲。

一、引言：为什么"模糊一句话写作 prompt"几乎注定会塌

先用一张图把这事说清。

一句"基于 URL 写博文"看似清楚，实则至少缺 5 类信号：

每丢一个维度，写作质量按几何级数下滑——5 个全丢（这是模糊 prompt 的常态），漏斗底部就是一篇没人想看完的稿子。

很多人遇到这个问题的反应是"换更好的模型 / 加更多形容词"。但形容词救不了你——“请深入分析、要有洞察、语言生动"这些词在数百万训练样本里被滥用过太多次，模型已经学会把它们当装饰品而不是约束。

prompt-optimizer 的思路很朴素：把"模糊"翻译成"具体的 5 个维度信号”，强制每个维度都要给出可执行的值。

二、Skill 是怎么造出来的：从一次糟糕的写作经验到一个可复用 skill

讲完痛点，先别急着看 skill 长什么样。一个好用的 skill 不是设计出来的，是从一连串失败案例里被"逼"出来的——下面把这个 skill 从概念到上线的完整开发过程拆给你看，4 个阶段，每个阶段都对应一个真实的失败 → 一个具体的决策。

阶段一 · 概念构思：先想清楚"不做什么"

最早的想法是做一个"通用 prompt 优化器"——任何模糊的 prompt 都帮用户改清楚。这个想法听起来很美，但很快被自己劝退了。原因有两条：

1. “模糊"的失败模式因场景而异。代码生成 prompt 的失败是"格式不合规、type 乱造”；写作 prompt 的失败是"没图、没结构、复述原料"；Agent 行为 prompt 的失败是"边界没写清、上下文管理失控"。你不可能用同一份维度清单去补所有场景。
2. 场景越宽，维度越虚。一旦尝试覆盖所有 prompt 类型，唯一能写出的东西就只剩"请清晰、请具体、请有结构"这种形容词级别的废话——而这恰恰是 LLM 已经学会无视的指令。

于是做了第一个关键决策——收窄场景：

这个 skill 只服务一类高频塌方需求：用户给一个 URL / 一份资料 / 一个主题，让 LLM 写一篇博客发表级别的图文长文。其它一切都不管。

这条原则上看是放弃了 90% 的潜在用户，但收窄 = 把"维度清单"做实的前提。后面的 5 维度心智模型只有在这个窄场景里才不是空话。

这也是 Anthropic 在 Skills 设计指南 里反复强调的——skill 不是越宽越好，“description 写清楚什么时候触发、什么时候不触发"是它最重要的工程能力。

阶段二 · 架构设计：主文档要轻，细节要分层

下一步要回答一个具体问题——SKILL.md 主文档里应该塞什么、不塞什么？

Claude Skills 的机制核心是渐进披露（progressive disclosure）：模型先看 description 决定要不要触发；触发了才加载 SKILL.md 主文档；主文档里再决定要不要进一步去读 references。这意味着——主文档每一行都会进入工作上下文，越长越占 token、越容易稀释关键信号。

按这个原则把内容分了三层：

prompt-optimizer/
├── SKILL.md                              ← 主文档（方法论 + 工作流 + 铁律）
│                                            注：被触发后必加载，要短而精
├── references/
│   ├── 5-dimensions-checklist.md         ← 5 维度的逐项检查清单
│   └── before-after-gallery.md           ← 跨领域对照范例
│                                            注：按需引用，长卷宗放这里
└── templates/
    └── optimized-prompt-template.md      ← 可直接 fork 的最终骨架
                                             注：模型主动 read 时使用

关键决策是——主文档只放"理解 + 决策"层面的内容（场景定义、5 维度心智模型、5 步工作流、反触发清单），所有**“长例子、详细对照、可复制模板"全部下沉到 references/ 和 templates/**。

主文档越短，模型越能记住核心动作；细节按需加载，反而执行得更准。这条原则在后面的评测里被反复证明有效——经过三轮 description 修订，主文档正文一行没动，因为它确实是"决策层"该有的样子。

阶段三 · 实现细节：5 维度怎么找出来的？Step 5 是怎么发明的？

主文档要写哪些内容？这是 skill 的核心实现问题。

5 维度从"失败模式逆推”

5 维度不是凭"我觉得写文章需要这几样"想出来的，而是从 LLM 在裸 prompt 下的真实失败模式逆推出来的：

先观察失败、再倒推维度——这个顺序很重要。如果反过来"先设计维度、再去匹配失败"，往往会陷入"维度无限增加但仍盖不住实际失败"的尴尬。

Step 5 这条铁律是怎么被发现的

5 维度补齐到位，已经能让 LLM 写出结构清晰的优化版 prompt。但实际使用中很快发现一个隐性失败模式——LLM 把优化版 prompt 写完后会"自然停下"，等用户再说"那现在开始写吧"。

这一停就毁了整个体验。

用户的真实期望从来不是拿到一段更漂亮的 prompt，用户想要的是文章本身——优化 prompt 只是手段。但模型不知道这一点，它觉得"优化 prompt 这个任务完成了，可以交差了"。

于是加了第 5 步铁律——Step 5：直接执行优化后的提示词（不要等用户再说一句"开始"）：

优化提示词的最终目的是产出文章，不是产出一段更漂亮的 prompt。所以 Step 4 输出完毕后，必须立刻把这条优化版提示词当作下一步的输入，直接开始执行写作任务。

这条铁律的本质是显式化了用户的隐性约束——“你优化完，我接着用”——并强制模型把它当成同一个任务的两个连续阶段。

后面的质量评测会反复看到这条铁律的威力：eval-1 baseline 直接停下不写，eval-4 baseline 改完 prompt 就停——这两个 case 上 with_skill 和 baseline 的差距，几乎全部来自 Step 5 铁律。

设计 skill 的反常识经验：找到那个"用户没说但显然想要"的隐性约束，并强制要求执行它，比写更长的指令更有用。

阶段四 · 定型上线：让 skill 知道自己什么时候不该上

最后一个决策是关于边界。

一个 skill 最容易翻车的地方不是"它该做的事没做好"，而是"它在不该上的时候硬上"——硬要给 commit message 加 4 张配图、硬要给 SQL prompt 写"引言 / 案例 / 总结"。一旦发生，用户体验比"没有这个 skill"还差。

于是把"反触发清单"放进了 description 字面（而不是只放在 SKILL.md 正文里）：

不要用于代码生成、数据查询、Agent 行为定义这类非写作 prompt；
也不要用于最终产物不对外发表的场景（如 commit message、内部邮件、
内部周报/RFC、PPT 大纲、slogan）——判断依据是"用户最终要交付什么"，
不是"原料来自哪里"。

为什么放在 description 字面而不是 SKILL.md 正文？因为 description 是 skill 召回时唯一被模型看到的东西。要让 skill 在被召回前就知道"我不该上"，必须把反触发清单贴到 description 里——只放在 SKILL.md 正文里，要等模型把整个 skill 拉起来才能看到，那时已经晚了。

这一条直接决定了后面触发评测能不能拿到 100% specificity——后面三轮迭代里 v2/v3 的演化，几乎全部是在改这条反触发线的措辞。

一句话回看整个开发过程

这 4 个决策连起来，是一条非常清晰的开发节奏——

收窄场景 → 分层架构 → 从失败模式逆推规则 → 显式标注边界。

注意：每个决策都来自一个具体的失败案例，而不是"我觉得这样比较优雅"。skill 开发是个经验驱动的过程，先有"它塌了"的观察，才有"我们该补什么"的设计。这一点在后面的评测里会被反复验证——三轮 description 迭代每一轮的修订，没有一处是凭直觉改的，全部是从 trigger eval 暴露的具体 query 失败案例反推出来的。

下面这一节就来看 skill 最终成型后长什么样——同样的内容你已经在上面的"5 维度 × 5 步"里隐约见过了，这次给它一个完整、静态的拆解。

三、Skill 长什么样：5 维度心智模型 × 5 步工作流

经过上面 4 个阶段，skill 最终成型后的核心由两个东西构成——一份 5 维度补齐清单和一份 5 步工作流。两者配合，把模糊 prompt 变成可执行的深度 prompt。

5 维度补齐清单（核心心智模型）

绝大多数"写博文"的模糊 prompt，在下面这 5 个维度里至少缺 4 个：

记住这张表。Skill 的所有动作都围绕"把这 5 个维度补齐"展开。

5 步工作流

Step 1 · 收集（不要急着改）
Step 2 · 5 维度补齐
Step 3 · 编排成最终提示词
Step 4 · 自检 + 一次缩减
Step 5 · 立即执行写正文 ⚡

前 4 步好理解。Step 5 是这个 skill 的灵魂——它强制要求"优化版 prompt 输出后，紧接着用它当输入立即开始写正文"，把 prompt 优化和正文产出做成同一次响应里的两个连续阶段，不要停下来问"要不要现在开始？"。

为什么这条很关键？因为大多数 LLM 在写完优化版 prompt 后会自然停下——它觉得任务完成了。但用户的真实目的从来不是拿到一段更漂亮的 prompt，用户想要的是文章本身。Step 5 把这个隐性期望显式化，根除了"优化完不写正文"的失败模式。

后面评测部分会看到，这一条铁律是 baseline 和 skill 在某些 case 上拉开差距的最大原因。

四、质量评测：with_skill 21/21 vs baseline 4/8

理论部分到此，接下来用数据说话。我设计了 5 个真实写作场景，每个跑两份：一份让子代理读完 SKILL.md 再执行（with_skill），一份不读 skill 直接按裸 LLM 本能反应（baseline）。然后用一组客观断言自动 grading。

5 个测试 case

eval-3 是一个陷阱用例——它看起来像"prompt 优化请求"，但 commit message 在 skill 自己的反触发清单里，正确行为应该是不走 5 维度博文流程。

客观断言通过率对比

总分：with_skill 21/21（100%） vs baseline 4/8（50%）。

但分数本身不是重点。重点是失败模式的差异——这是评测最值钱的部分。

三大失败模式被 skill 完全消除

失败模式一：遇模糊 prompt 不敢动笔写

eval-1（纯主题深度文）的 baseline 子代理收到"写一篇 AI Agent 2026 趋势的深度文章"后，直接停下来报告"工具不足、信息不够、请补充澄清"。它没有写任何文章。0/1 通过。

而读了 skill 的子代理直接进入产出——按 5 维度补出"AI 应用开发者 / 6 条结构性趋势 / 三段式论证 / 每条趋势配概念图"等约束，一口气写出近 8000 字符的完整产出（优化版 prompt + 完整正文 + 7 段配图描述）。

这正是 Step 5 铁律存在的意义。

失败模式二：优化完 prompt 就停下，不写正文

eval-4 是更典型的差异点——用户说"帮我把这条 prompt 改清楚一点：写一篇讲 Claude Skills 的文章"。

• baseline：给出了一份漂亮的"改写后 prompt + 7 个改写维度对照表"，然后停了。它觉得任务已经完成。
• with_skill：先给优化版 prompt，紧接着一句过渡话——“下面按上面这条提示词直接开写——"，然后产出整整一篇带 5 节配图描述的深度博文。

baseline 在客观断言上其实也通过了（因为我的断言只测"是否给了 prompt 优化建议”），但实际质量塌——用户得到的不是文章，是一份"作业说明"。这个差异在表面分数上看不出来，要看实际产物才能感知。

失败模式三：原料缺失硬编内容

eval-0 让子代理基于一个 URL 写博文。但子代理（code-explorer 子代理）实际没有 web_fetch 工具。

• baseline：基于训练数据印象硬编内容，文章里出现 via.placeholder.com/800x400.png?text=Claude+Skills 这种假图链。事实细节多处与官方说法对不上。
• with_skill：按 SKILL.md 的「Step 5 例外条件②」正确停下，报告"原料缺失，请补料"——给出 4 种补料方式让用户选。

这正是 skill 反模式条款"不要让 LLM 在没读原料的情况下产出"想防住的——不在原文支撑下铺出来的内容，再漂亮也是污染。

五、触发评测：F1 从 0.90 到 1.00 的三轮迭代

质量评测告诉我们 skill 被触发后能干好活。但还有另一半问题——它会不会在该触发时被触发，在不该触发时被准确拒绝？

这就是触发评测要解决的问题。我设计了 20 个 query（10 应触发 + 10 不应触发，包含口语化、错别字、近似命中等真实用法），每个 query 由独立子代理判定 3 次（多数票决定最终是否触发）。

三轮迭代的完整轨迹

iter1 是基线评测——结果发现 description 已经"够用"但有 3 个边界洞：q4 弱判定、q10 漏召、q20 误召。

iter1 → iter2：3 处补丁拿满分

针对 iter1 暴露的 3 个边界，v2 做了 3 处对症下药的修订：

1. 触发线 A 末尾追加 "或给一段自己写的初稿要求重写为博文" → 修 q10
2. 新增一句判定标准："判定模糊的标准是没说清受众/结构/视觉/风格——即便主题明确、字数指定，缺这些信号仍算模糊" → 修 q4
3. 反触发线扩展：从代码生成 / 数据查询 / Agent 行为定义扩到 commit message / 邮件 / 内部报告 / 内部 RFC → 修 q20

字数 153 → 217。改完拿到 F1 = 1.00。

iter2 → iter3：分数停在 100% 之后还能进步

很多人会在 F1 = 1.00 时收手。但触发评测里有比"分数"更细的信号——v2 虽然 100% 准确率，但 q3 出现了 2/3 弱判定（其它 19 个都是 3/3 全票）。

挖一下原因：

q3 用户输入（精简）：「我把老板发的内部讨论稿贴下面……帮我改写成可以发在公众号上的深度解读」

q3 的第一票判 false，理由是："内部讨论稿，description排除内部RFC"——子代理只看到"内部讨论稿"几个字，匹配上 v2 反触发线里"内部 RFC"，就判 false 了。它没看完整句话——输入是内部稿，但产物要发公众号。

这是 v2 反触发线的措辞副作用：“内部 X” 变成了过强的字面信号。

修这个的关键洞察是：判触发与否，应该看用户最终想要什么（产物形态），而不是用户给我的原料是什么。

v3 把反触发线整体重构：

v2: 不要用于 ... commit message / 邮件 / 内部报告 / 内部 RFC 这类非"对外发表"的写作 prompt。
        ↓
v3: 不要用于代码生成、数据查询、Agent 行为定义这类非写作 prompt；也不要用于
   最终产物不对外发表的场景（如 commit message、内部邮件、内部周报/RFC、
   PPT 大纲、slogan）——判断依据是"用户最终要交付什么"，不是"原料来自哪里"。

字数 217 → 257。改完跑回归：

• ✅ q3：vote 2/3 → 3/3
• ✅ q17/q18/q19（翻译/PPT/slogan 反例）confidence 都从 4.0 升到 5.0
• ✅ 0 硬回归 + 0 共识弱化
• ✅ 全样本 20/20 全票一致，平均 confidence 推到 4.60

至此触发评测真正触顶——分数 100%、一致性 100%、平均坚定度 4.60/5。

两条反常识结论

跑完这三轮，沉淀下来两条值得记住的判断：

① description 的护城河，是"看产物不看原料"

iter2 → iter3 的修订没有加新规则，只是把判据从"原料类型"改成了"产物去向"。这一句"判断依据是用户最终要交付什么"是整个 description 里最值钱的一句——它替代了对反例的字面列举，让模型自己去想清楚每条 query 的本质。

写 skill description 的常见误区是把反例列得越长越好。但反例越长，字面冲突越多——v2 的"内部 RFC"在 q3 上踩中的就是这种坑。让模型理解判据的"原则"，比给它一个"反例清单"更稳。

② 触发评测能找到质量评测找不到的问题

q3 在质量评测里是完美通过的——它属于 eval-2（资料型解读），with_skill 在那个 case 上拿了 6/6 满分。如果只看质量评测，你会觉得 description 没问题。

但触发评测让 60 个独立子代理只读 description 不读正文，就直接暴露了 description 的字面陷阱。这是质量评测做不到的——质量评测是"模型已经被触发后能干多好"，触发评测是"description 字面措辞的稳健性"。两者都做才能看到全貌。

六、三轮迭代复盘：每一轮的"洞察"长什么样

关键工程实践——每轮迭代都做了 3 件事：

1. 明确目标：列出要修复的 query 编号 + 期望结果（“q3 vote 应从 2/3 提升到 3/3”）
2. 跑回归：用同一份 20 query 全跑一遍，确认 0 硬回归
3. 多维指标：除 F1 外，还看"3/3 全票数"、“平均 confidence”——这些副指标在分数饱和后还能告诉你 description 是否真的稳

第 3 点特别重要。不止一个评测告诉你"100% 后还能改"：confidence 从 4.28 → 4.45 → 4.60 的爬升，3/3 全票从 17 → 19 → 20 的提升，都说明 description 不是只"答对"了，还在变得更难被字面误读。这种"鲁棒性"的提升在分数上看不见，但在生产环境里直接决定你的 skill 在边角 query 上是否会忽然失常。

七、什么时候你应该用 prompt-optimizer

写完了三轮评测，回头看，这个 skill 适合的场景其实非常明确——

四条都满足，就用 skill：

1. 产物是对外发表的深度博文（不是 commit / 邮件 / 内部 RFC / PPT / slogan）
2. 不属于代码生成 / 数据查询 / Agent 行为定义这些非写作 prompt
3. 原始 prompt 没说清受众、结构、视觉、风格四个信号中的至少一个
4. 你接受 skill 在优化完 prompt 后立即接着写正文（这是默认行为）

否则就不用——硬套博文流程会引入"配图"“分章节"等无关约束，反而降低产出质量。eval-3 那个 commit message 用例就是反例：with_skill 子代理读完 SKILL.md 后正确识别"这不是博文场景”，没有走 5 维度流程，而是切换到普通 prompt 设计建议。这种"知道自己什么时候不该上"的能力，比"什么场景都强行套用"更值钱。

八、总结：评测 skill 的 7 条带走清单

如果你也想给自己的 skill 做一次类似的双轨评测，下面是这次实验留下的可复用经验：

1. 质量评测和触发评测要双轨跑。前者看"被触发后能干多好"，后者看"description 字面措辞的稳健性"。两者答案经常不一样。
2. 测试用例里要塞反触发用例（eval-3 commit message、q15 改 skill description 等）。这些近似命中的边界比正向用例更能暴露 description 的薄弱处。
3. 触发评测每个 query 跑 ≥ 3 次独立判定。多数票决定 verdict，但少数票（2/3）本身就是信号——告诉你 description 在哪条边界上不够稳。
4. F1 之外还要看 confidence 和 3/3 全票一致率。分数停在 100% 之后这两个指标还能继续暴露问题。
5. description 修订要可回归。每改一处都跑同一份评测集，确认 0 硬回归 + 0 共识弱化才落地。
6. 判断依据写"原则"比写"反例清单"更稳。反例越长字面冲突越多，原则一句话覆盖一片。
7. skill 的核心铁律比 5 维度更难发明。prompt-optimizer 的 Step 5「优化即执行」是这个 skill 真正的灵魂——它根除了一个隐性失败模式（优化完不写正文）。设计 skill 时，找到那个"用户没说但显然想要"的隐性约束，并强制要求执行它，比写更长的指令更有用。

最后留一个值得自己琢磨的问题——

你写过的 prompt / skill / system prompt，有没有跑过类似的双轨评测？如果没有，你怎么知道它真的有用？

评测不是上线前的可选项，评测是你的 prompt 真实质量的镜子。这次实验完整跑下来花了不到 1 小时，但回报是：从此对这个 skill 的能力边界有底了——知道它什么时候稳、什么时候会失常、改一行字会带来什么副作用。

本文用到的全部脚本、20 query 评测集、180 次召回判定的原始数据、三轮 iteration 报告，都在仓库 .codebuddy/skills/prompt-optimizer-workspace/ 下，可复跑可扩展。

× 爱折腾的工程师

真诚赞赏，手留余香

2元 5元 10元 50元 100元 任意金额

2元

使用微信扫描二维码完成支付

• ← Previous Post