agentleFS
unravel11unravel11/research-paper-skills/.claude/skills/paper-storytelling/SKILL.md

paper-storytelling

Skill0 starsChanged 27 days agoMITView on GitHub

把论文当作一个要打动读者的故事来设计与检查:产出"故事骨架"(读者、原信念、张力、转折、收获),并用它约束标题、摘要、引言、图一、各 RQ 的回答与结论。用于 framing 锁定主张之后、写作开始之前,以及初稿读起来像实验报告、审稿人说 incremental / 看不出意义、或用户要求"讲好故事 / 让论文打动人"时。不编造证据,不为故事改结果;不用于单段润色、文献综述或图表绘制本身。 英文触发短语:story spine, tell a better story, make the paper compelling, it reads like a lab report, Figure 1 judgment, answer-to-RQ box, six-step introduction, the one-sentence story, settle the story branch after results.

The file

Files
SKILL.md

Paper storytelling:让论文打动人

事实正确的论文可以完全无法打动人:从陈述背景开始,把数字逐个念完,结论再念一遍。读者读完不知道自己为什么要在乎。 本 skill 的任务是在证据边界内,让读者在第一页就产生"这件事和我有关,而且我原来想错了"的感觉,并一路带到收获。

两条底线高于一切:不编造或挑选证据来服务故事;主张强度只能由证据决定,故事只决定呈现顺序和重心。

1. 什么时候用

  • 主线已由 paper-framing 锁定(主张、RQ、读者价值已有草案),尚未开始写正文:先做故事骨架。
  • 初稿已有但读起来像实验日志:用第 4 节的症状清单诊断,再回到骨架重排。
  • 审稿意见是 incremental、limited significance、unclear contribution:先按 paper-framing/references/reader-visibility.md 判断是不是叙事不可见;是,才用本 skill。
  • 在 research-pipeline 里的位置:R1 的第二步(paper/FRAMING.md 之后、R2 协议之前)产出带分支的骨架;R3 之后结算分支并归档 R1 版本;R4 时 orchestrator 的 S2 核对结算、S3 决定图一与各部位的写法、S4 用第 4 节的症状清单当门槛。

阶段锁:本 skill 只产出骨架与呈现决定,不设计实验、不修改结果、不替写整篇正文。

2. 故事骨架(必过门槛)

按 story-spine-template.md 写,每项一两句话,全部能追溯到台账里的证据或有依据的文献:

  1. 读者:具体到职业和处境,不是"研究者"。
  2. 原信念 / 现做法:读者今天怎么做、为什么这么做。要有出处(文献、工业实践、本文基线),不树立稻草人。
  3. 张力:哪个事实让原做法变得不舒服(代价、失败、矛盾)。张力必须是读者已经感到或一看就承认的,不是作者制造的。
  4. 转折:本文发现的那个让局面改变的关键事实。只允许一个。实验之前写时按分支写:主要比较成立是什么转折,不成立是什么转折。不成立也能是转折,例如"小模型不知道自己什么时候错",前提是协议里的结果中性检查通过,让它是发现而不是失败。
  5. 收获:读者读完后会改变哪个决定;适用边界是什么。每个分支各写,并写下这个分支适合的 venue 候选;不成立分支要有退路。
  6. 一句话故事:把 1–5 连成不超过 40 字的一句话,每个分支一句。删掉它,论文的组织就应该散架;删不散架,说明骨架还没抓到。每个分支各做一次删除测试。

读者、原信念、张力三项不依赖结果,R1 就写死。骨架完成后停下来给用户看。用户不认,回到 paper-framing 重新定主张,不在本 skill 里硬圆。

R3 之后做结算:把 R1 版本复制为 paper/STORY_SPINE_R1_<date>.md 归档,按台账选定一个分支填进"结算"节,落实决定只按选定分支写。不把两个分支揉成一个;选中分支依赖的证据状态不是 VERIFIED_CURRENT,或两个分支都站不住,回退 R1。先有结果的项目分支已由结果决定,结算与 R1 一并完成,时点写事后。

3. 用骨架约束各部位

部位要求
标题含转折或收获,不含方法名堆砌;读者看标题能猜到收获
摘要第一句是张力或读者处境,不是领域背景;最多 3–5 个数字,每个数字都对应骨架的一环
引言顺序固定:读者处境 → 原做法 → 张力(带一个真实的动机示例)→ 转折 → 收获与边界 → 贡献列表。贡献列表最多 3–4 条,第一条就是转折
图一单独一张图就能讲出转折;放在第 1–2 页;图题第一句是结论句
每个 RQ结尾一个"Answer to RQx"框:一句结论 + 一句对骨架的回扣(这条结果让转折或收获的哪一部分成立)
讨论从"收获"展开:读者明天会怎么做不一样;边界与反例要和张力同样具体
结论重述一句话故事和边界,不重复数字
负面与消融结果作为"为什么转折成立 / 哪些捷径不成立"的支撑放进去,压缩成一表一段;它们不是贡献

更多写法见 intro-and-figure-one.md。

4. 实验报告症状清单

初稿出现以下任一症状即不合格,回到骨架重排:

  • 摘要或引言第一句是领域背景陈述。
  • 引言没有动机示例,或示例不是真实数据。
  • 前两页没有一张能单独讲出转折的图。
  • 一句话里有三个以上数字或区间。
  • 方法用内部代号(运行编号、arm、协议编号、某某变体)而不是读者能记住的短名。
  • RQ 结尾没有一句结论,只有数字和判定规则。
  • 结论只是把数字重复一遍。
  • 贡献列表里一半是负结果或消融。
  • 过程叙述(为什么换方法、什么时候定规则)出现在引言或方法正文而不是威胁有效性或附录。
  • 删掉所谓的中心主张后,章节顺序不需要变。

5. 不允许的事

  • 为了张力虚构共识、挑一个反方向的格子、把单次运行的偶然当反转。
  • 把"读者会改变决定"写成已被验证,除非确实测量过。
  • 用故事掩盖负结果、单次运行;这些照实写。补做的分析叫"分析",不说成"验证"。
  • 把"打动人"理解为形容词、宏大词或反直觉姿态。打动人靠具体:具体的读者、具体的代价、具体的例子、一张清楚的图。
  • 换 venue 时改转折或主张强度。venue 只能改读者与收获的措辞、相关工作的邻域和展开深度。

6. 交付

  • paper/STORY_SPINE.md:读者、原信念、张力 + 每个分支的转折、收获、一句话故事与删除测试 + 结算节 + 落实决定 + 对台账证据的引用。R3 之后另有归档的 R1 版本 paper/STORY_SPINE_R1_<date>.md。
  • 图一与图表的决定同步写进 paper/FIGURE_PLAN.md(research-pipeline 项目骨架里的文件;"一句结论"就是图题第一句)。有 research/STATE.md 时更新 R1 的门槛核对与下一步。
  • 若诊断初稿:症状清单逐项勾选 + 最小改动顺序(先图一和引言,再 RQ 回答框,最后摘要与标题)。
  • 结束时提示下一步可用的 skill(paper-style-profiler 定风格锚点、publication-chart-skill 出图、paper-writing-orchestrator 继续写),不替用户启动。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.