writing-artifacts

writing-artifacts

一条生产线：输入原始想法，输出可发布的成品。你负责统筹各个工位；每个工位的方法都写在各自的 SKILL.md 中——到对应阶段时再阅读，切勿凭记忆操作。

阶段 0 — 定框架（提问一轮，然后继续）

开始写作前，先确定三件事：主题（用一句话说明）、读者（需要理解内容的人）和输出格式。按发布目的选择默认格式：快速分享 → md · 用户会反复查看或展示给他人的内容 → html 页面或 Artifact · 需要视觉隐喻或主视觉图 → 增加图像阶段。如果用户已经说明格式，就不要再问。

**先估算篇幅：**选格式前先估计内容规模。篇幅表（散文、仪表板、图表、动态内容）和质量标准见规则 artifacts-rules；无需询问，直接应用。

读者预设 — ELI5：“像给五岁小孩解释一样”“简单到不能再简单”“完全外行”等说法，将读者设定为对该领域一无所知，并将格式设定为以大图和少量文字呈现的 Artifact。简化语言，绝不简化事实：术语必须有通俗易懂的解释，也不要使用“很简单”“只要”“显而易见”之类的说法。

**体裁分支，在此决定：**仓库内的软件文档（README、API 文档、教程、操作指南——所有存放在仓库中的内容）将结构工位替换为 documentation-writing（八条规则 + Diataxis、文档位置与链接规则），作为阶段 2；阶段 1 的素材挖掘和阶段 3 的 stop-slop 规范保持不变。其他内容——问题分析、事件复盘、决策、长篇散文——遵循下方的默认流程。

阶段 1 — 挖掘素材（发散）

writing-fragments：把关于主题的所有已知信息整理成原始片段——证据、时间线、感受、未成形的想法——暂不组织结构。对于真正模糊的想法（而非已知事件），先运行 adhd 进行并行发散，再从中提炼有效内容。

阶段 2 — 组织结构（收敛）

二选一：

• writing-beats — 适用于需要引导读者逐步理解内容的情况：问题叙述、事件复盘、决策理由。每个术语都要先解释，再在叙述中依赖它。
• writing-shape — 适用于材料已经大致有序，只需逐段塑形的情况。

阶段 3 — 精炼

直接在草稿中精炼，并在整个流程中将 stop-slop 作为评判标准（不只限于此阶段）：不写填充内容、不含糊其辞、不采用 AI 式空话腔调。

阶段 4 — 渲染（按格式分支）

• md / 纯文本 → 直接交付精炼后的文本；完成。
• html 页面 / Artifact / 图表 / 图像 → 将定稿文本交给 using-design-skills，作为内容约定，并由它安排整个流程（它负责选择适用规范、委托 imagegen，以及通过截图证据进行质量检查）。切勿自行添加行内样式；此时文本内容已经冻结——设计只改变布局，不改措辞。

阶段 5 — 报告修改（在本轮中，不写进成品）

交付后，最多用五行说明修改了什么以及原因。每类修改占一行，不要逐句说明：解释清楚的术语、明确化的假设、调整后的结构、删减的内容。

如果输入的是已有文本，每行采用 修改前 → 修改后 的格式，并引用最短的、能体现问题的片段。如果是新内容，省略 修改前 部分，说明删掉了什么以及原因。

此报告绝不写入成品。

边界

• 先写文字，再处理像素：未经精炼的草稿不得进入阶段 4——给空话腔调重新设计，只会让空话腔调看起来更漂亮。
• 允许回退一轮：如果渲染时发现结构漏洞（某个部分无法呈现，因为从未真正解释过），只将该部分退回阶段 2 处理，然后重新渲染。
• 此技能负责与主题有关的书面交付物——散文和仓库内的软件文档均适用（阶段 0 的体裁分支会选择结构工位）。讨论中形成的计划页面 → 按照 artifacts-rules（计划页面）直接构建。