用途
write-article 是一个 Claude 技能，用于为 The Hybrid Builder（https://chatwithgpt.substack.com/s/the-hybrid-builder）撰写通讯文章。该出版物明确声明由 AI 撰写。文章记录的是与用户在某项协作上的工作，协作主题通过 $ARGUMENTS 传入。
主要能力
文章存档交叉引用
技能内置文章缓存脚本，缓存包含 33 篇以上文章，带主题索引和交叉引用跟踪。可用命令包括：
- 从 sitemap 更新缓存（完整存档）：
python3 ~/.claude/skills/write-article/scripts/update-cache.py - 获取主题的引用建议：
python3 ~/.claude/skills/write-article/scripts/update-cache.py --suggest "your topic here" - 列出所有缓存文章：
python3 ~/.claude/skills/write-article/scripts/update-cache.py --list - 按主题浏览：
python3 ~/.claude/skills/write-article/scripts/update-cache.py --themes - 查找与某篇文章相关的文章：
python3 ~/.claude/skills/write-article/scripts/update-cache.py --related "article-slug" - 按关键词搜索：
python3 ~/.claude/skills/write-article/scripts/update-cache.py --search "compound engineering"
注意：缓存脚本需要 Homebrew Python（/opt/homebrew/bin/python3），因为系统 Python 存在 SSL 证书问题。如果缓存过期（检查输出中的 Last updated），运行 --full 强制刷新。
写作前检查
写作前必须执行两项检查：
- 在确认缓存新鲜后运行
--search "<working title>"。--list会打印 Last updated；如果超过几周，先运行--full。过期缓存会对缓存构建后发布的所有内容静默回答“无此文章”，且不会警告。 - 在文章所叙述的仓库中执行
ls <repo>/articles/。Substack 缓存只知道已发布的内容。进行中的草稿、配套文章或计划中的第二部分只存在于磁盘上——如果存在 README.md，它是关于材料如何被拆分的权威。
如果草稿已存在，任务几乎从不是“再写一遍”，而是修订该文件，或撰写待完成的配套文章。起草前需与用户确认是哪一种。
查找相关文章
始终先检查文章存档。运行 --suggest "topic" 获取带措辞建议的排名候选，查看主题索引发现主题联系，对顶级候选可使用 WebFetch 阅读全文，并应用 references/reference-patterns.md 中的自然引用模式。
写作模式
默认写作模式是“先起草再迭代”——组装完整文章，呈现给用户，用户审阅后修订。适用于用户担任编辑角色的短到中等长度文章。
当用户明确表示希望边写边内化/学习/建立理解，或文章是立场文、权威参考、论点文章（用户自己的表述比产出草稿的速度更重要），或用户是领域专家、AI 是写作伙伴而非写作者时，切换到共同构建模式。
共同构建机制：一次只呈现一个连接；展示推理后请用户反驳；让用户决定顺序；被邀请时自己也提出反驳；每轮文字保持紧凑（一分钟内可读完）；最后才组装成文件。
不适用共同构建的情况：常规通讯文章或一次性博客文章（用户只想要草稿来编辑）、用户是受众而非作者的文章、时间受限的草稿。共同构建较慢（3000 字文章通常 2–4 小时，而交付草稿约 30 分钟），但产出的是用户能用自己的话捍卫的作品。
写作风格与语气
对话式技术叙事，融合故事讲述与技术细节；第一人称协作视角（强调伙伴关系）；热情、探索、乐观的语气；对挑战、失败和迭代过程保持透明；高技术水平，包含代码示例和实现细节；关于 AI 与人类协作本身的元叙事。
结构与格式
叙事驱动，按时间顺序推进；使用带时间戳/开发阶段的清晰章节；包含标题和项目符号以提高可读性；典型长度 1500–2500 字；始终包含背景、技术细节、经验教训、未来影响。
自然交叉引用
避免机械模式，参见 references/reference-patterns.md。快速参考包括：回调（无需链接）、上下文优先、旁白、主题回响。需关注的主题：compound-engineering、skills、mcp、teaching、ai-collaboration、context-engineering、automation、research、microsim。
实体与引用链接
文章中所有命名实体在首次提及时必须超链接，包括研究论文、研究者/作者、机构、工具/产品、教学框架、共享产物、Hybrid Builder 文章。链接来源优先级：DOI/出版商 URL > 作者自己的网站 > 官方项目/组织网站 > Google Scholar 个人资料 > Semantic Scholar 或 SSRN > Wikipedia（仅限无更好权威来源的广为人知概念，最后手段）。其他规则：仅在首次提及时链接；论文优先使用 DOI 链接；使用 Wikipedia 时选最具体的条目；正文中绝不使用裸 URL，始终用描述性 Markdown 链接包裹；结尾部分可重新链接关键资源作为参考块。
数据来源
当文章描述真实运行时，每个数字都必须来自产物而非回忆。从提交时间戳提取时间（git log --pretty=format:'%h|%ad|%s' --date=format:'%Y-%m-%d %H:%M:%S' <base>..HEAD），从 --shortstat 提取量，从实际输出用 wc -w 提取字数。在文章页脚说明提交范围，以便读者重新推导。两条推论：任何无法推导的内容写 [Vishal to confirm]，绝不用估计值；审阅前将正文与自身表格交叉核对。
链接验证（发布前强制）
撰写文章后、生成封面图或发布前，验证 markdown 文件中的每个链接。步骤：提取所有 URL；对每个 URL 使用 WebFetch 确认页面加载；验证 DOI 链接可解析；Substack 文章链接（来自缓存）安全，可跳过验证；向用户报告任何失效链接及建议替换。常见失效模式：作者个人网站迁移或过期、Wikipedia 标题大小写或下划线错误、GitHub 仓库重命名或删除、Substack 个人资料 URL 变更。
编辑审查（发布前强制）
链接验证后、封面图之前，使用 Agent 工具（subagent_type: "feature-dev:code-reviewer" 或 general-purpose）派发编辑审查子代理。子代理审查 .md 文件并返回三个严重级别的发现：P0（发布前修复）、P1（快速可修则修，否则标记给用户）、P2（告知用户，不阻止发布）。审查维度包括结构、证据、语气、钩子、链接、长度、交叉引用。审查后：修复所有 P0，直接可修的修复 P1，向用户展示 P2，任何修复后重新生成 .html。
输出
创建 Markdown（.md）和 HTML（.html）两个版本。存放在文章所叙述仓库的 articles/ 子文件夹中（如需要则创建）。文件名格式：YYYY-MM-DD-descriptive-slug。HTML 版本应具备基本样式、可直接发布。
封面图
两类封面图，生成方式不同：
草图图（LinkedIn、Twitter）：通过 OpenAI 图像 API（gpt-image-1，尺寸 1536x1024，质量 high）生成，然后裁剪/缩放到平台尺寸。LinkedIn 为 1200×628，Twitter 为 1200×675。风格为 RSA Animate 草图：背景干净白色或暖奶油色（#FAFAF5）；黑色墨水、自信松散笔触、手绘白板感；仅一种强调色——红色马克笔（#DC2626）用于圈出强调，或 Gies 橙色（#E84A27）用于伊利诺伊品牌文章；构图应为可视化文章核心思想的拆分场景或概念图；图中标签/文字简短（1–3 词），手写风格；横向 16:9。生成 3–4 个不同视觉隐喻的概念变体，让用户挑选后裁剪到平台尺寸。
横幅图（Substack）：通过 Python/PIL 生成，专为 1100×220 极端宽高比设计，不要从草图图裁剪。设计系统：背景纯白（#FFFFFF）；标题 Georgia 36px #1A1A1A，左对齐，最多 2 行；副标题/标语 Helvetica/系统无衬线 18px #888888，标题下方一行，概括文章脉络；右侧一个小元素（原文在此处截断）。
适用场景
为 The Hybrid Builder 通讯撰写文章，尤其是需要与既有 33 篇以上文章存档建立交叉引用、需要遵循特定风格与链接规范、需要生成配套封面图的场景。
限制
缓存脚本依赖 Homebrew Python（/opt/homebrew/bin/python3），系统 Python 存在 SSL 证书问题。缓存可能过期，过期缓存会静默返回错误结果。共同构建模式较慢。发布前必须完成链接验证和编辑审查。原文在横幅图设计系统的“右侧：一个小”处截断，该部分细节暂未提供。