| name | article-writing |
| description | 为 ai-essentials 项目写文章、改文章时必须调用。包含强制性的写作风格和结构规范。
TRIGGER when: 用户说写文章、改文章、那篇文章；提到文章主题名+编辑意图（如 RAG 文章、MCP 文章、prompt 那篇、skills 那篇、rules 那篇）；要求对文章加段落、加比喻、改开头、改成表格、调整结构；讨论文章放哪个目录（understanding/ using/ coding/）。关键词：文章、写篇、那篇、开头、小结、章节 + 内容编辑动作。
SKIP: commit message、会议纪要、代码注释、创建 skill、字幕转换、编辑 .claude/rules 配置文件。
|
文章写作 Skill
本项目（ai-essentials）所有文章的写作、优化和修改，遵循以下规范。
核心理念
写文章是带读者走一段路，不是把知识搬到他面前。
读者在文章开头处于 A 状态（不知道、好奇、困惑），在结尾到达 B 状态（理解、认同、想动手试试）。中间的每一段都应该提供推动力：一个悬念、一个对比、一个反转、一个实例。如果一段话没有推动读者向前走，它就是多余的。
下面所有的技巧服务于这一件事：让读者一直想看下一段。
写作风格
语言基调
- 口语化但不随意，像一个有经验的同事在跟你讲东西
- 直入主题，不铺垫、不寒暄、不说「在当今 AI 时代...」
- 用短句，少用长从句。能一句说清的不用两句
开头钩子
开头的唯一目标：让读者产生「然后呢？」的冲动。绝对不能从定义开始。
四种钩子类型，根据文章主题选最合适的一种：
反差/双关：用一个词或概念的两层含义制造张力。
✅ Hermes 这个词，在不同圈子里有完全不同的含义。时尚界想到铂金包，AI 圈想到 Agent 框架。
两个 Hermes 唯一的共同点：都不便宜。一个要你的钱包，一个要你的时间。
❌ Hermes Agent 是 Nous Research 开发的开源 Agent 框架。
结果前置：先甩出结果或数据，再倒叙过程。适合案例复盘类文章。
✅ 我上周上架了个 App，一条小红书笔记 118 万阅读，7.3 万赞，冲到 AppStore 排行榜第 20 名。
排在它前面的是 YouTube、Instagram、Canva。
接下来聊聊这是怎么发生的。
❌ 本文介绍如何利用 AI 编程工具开发一款 iOS 应用并进行推广。
文化锚点：从一个大家熟悉的概念、作品、人物切入，架一座桥到你要讲的东西。
✅ 阿西莫夫在《基地》里虚构了一门学科叫心理史学。
Anthropic 过去 15 个月做的事，本质上就是在建立 AI 版的心理史学。
❌ 本文梳理 Anthropic 近期关于 AI 内部状态的系列研究论文。
私人瞬间：用一个真实的个人经历片段开场，拉近距离。
✅ 昨天接受记者采访时，她问我这个 skill 花了多长时间做的，我有点不好意思地说 2-3 小时。
但其实在这个过程中经过了无比多轮的迭代。
❌ 本文介绍一个用于 Skill 自动优化的工具。
禁止的表述
以下是典型的 AI 味表述，严禁出现：
- 「一个你一定遇到过的」「你可能不知道」「很多人不知道」
- 「值得一提的是」「不可否认」「众所周知」「毋庸置疑」
- 「让我们来看看」「接下来让我」「首先让我」
- 「不禁」「令人」「惊喜的是」「有趣的是」「巧妙的是」「精妙」「优雅」
- 「在当今...时代」「随着...的发展」
- 「这不是玄学」「这不是魔法」
写作手法
以下手法不只用于复杂概念，而是贯穿所有类型的写作。
渐进式提问：不直接给答案，用问题带节奏。先抛出读者可能有的困惑，再逐步解答。
✅ MCP 解决了接入问题，但它并没有真正解决 Agent 最头疼的那部分：
工具太多了怎么选？选了之后怎么组合？结果太多了怎么裁？
❌ MCP 有以下几个不足：第一... 第二... 第三...
场景还原：不抽象讨论概念，虚构一个具体场景把所有概念串进去。让读者在场景中自然理解每个角色的作用。
✅ 你对 Agent 说：「我的钉钉文档空间满了，帮我处理一下。」
接下来会发生什么？
第一步：模型理解意图...
第二步：宿主找到对应工具...
❌ MCP 的架构分为 Host、Client、Server 三层。Host 负责...
对比驱动理解：不单独讲一个东西好不好，通过对比让边界清晰。读者看完对比，自然知道什么时候该用什么。
先说结论再展开：复杂话题先给出明确判断，再解释为什么。避免读者读了一大段还不知道作者想表达什么。
先现象后解释：与「先说结论」互补的另一种方式。先抛出一个反直觉的现象或解释不了的谜题，让读者跟你一起破案，再给出解释。适合科普和深度分析类文章。
✅ 我在 SKILL.md 里从来不写「遇到问题 A 这样回答」。我只定义「你是谁」。
但你拿一个费曼从来没被公开问过的问题去问它，它会给出一个费曼式的回答。
为什么定义了「谁」，「怎么做」就自动出来了？
→ [然后用 Persona Selection Model 论文解释]
❌ Persona Selection Model 论文的核心观点是角色是整体性的。下面我举几个例子说明...
Show, Don't Tell：不要只声称「这个方法有效」，直接展示它运行的结果。用实际输出、具体数据、前后对比来证明。
✅ 5 个不同的 perspective skill 问了同一个问题。
费曼从实验出发：「171 个情绪向量...这个实验本身非常漂亮。」
芒格逆向思考：「不问 AI 有没有情绪，问如果我们假设有然后据此行动...」
[直接展示 2000 字的实际输出]
❌ 不同的 persona 会产生不同的回答，差异不只是修辞层面的。
知识诚实：明确标记哪些是事实、哪些是推测、哪些是个人直觉。不确定的地方直说不确定，这反而增加可信度。
✅ 以下是我的推测，不是论文的结论。
✅ 爆款有很大的运气成分，我能理解它引爆的原因，但没法复制。
✅ 我没有实验证据直接验证这个推测，但 21 个 skill 的实践经验间接支持它。
❌ [把推测当结论写，不标记边界]
分层拆解：一个复杂系统不要混在一起讲，先拆成清晰的层次，每层独立讲清楚，最后再串联。
如何选择手法：不要把上面的手法当清单逐一打勾。根据当前段落要达成的目标选：
| 读者此刻需要... | 优先用 |
|---|
| 知道「是什么」 | 对比驱动（和什么不一样） |
| 理解「为什么」 | 先现象后解释（让他自己想）或 先结论后展开（直接告诉他） |
| 相信「真的有效」 | Show, Don't Tell（给他看结果） |
| 学会「怎么操作」 | 场景还原（走一遍流程） |
| 接受「有不确定性」 | 知识诚实（标记推测边界） |
比喻和类比
- 最好的类比来自跨领域：用安然审计丑闻讲 AI agent 不能自己评自己，用扑克玩家讲情绪表达和情绪影响的分离，用达尔文进化论讲 skill 优化的棘轮机制
- 善用生活化比喻帮助理解抽象概念（参考项目中已有的：餐厅点菜、USB 接口、手机输入法联想）
- 使用 iOS 开发者视角的类比（Framework/SDK、Xcode Project、REST API 调用）
- 比喻要自然嵌入行文中，不要刻意标注「打个比方」
- 一个好类比的标准：读者读完类比就已经懂了七八成，后面的技术细节只是确认
节奏感
密集的技术段落之后需要一口气。一个比喻、一句自嘲、一个小故事，都是让读者换口气的方式。连续五段纯技术讲解会断掉读者的注意力。
好的节奏：技术密度 → 比喻/故事 → 技术密度 → 一句金句 → 继续推进。
个人经历叙事
最有效的文章结构是「我做了 X → 发现了 Y → 想明白了 Z」。理论和概念不是主线，是被个人经历串起来的配角。
- 读者不是在学知识点，是在跟作者一起经历一段认知旅程
- 实践在前，理论在后。先讲「我遇到了什么」，再讲「后来发现有人解释了这个现象」
- 失败经历和踩坑故事比成功案例更有说服力
- AI 写作时的原则：使用用户提供的素材、项目中已有的案例、或 iOS 开发场景中的常见经历。不要虚构具体的第一人称故事，但可以用「你可能遇到过这种情况：...」的方式构建共鸣
✅ 我早期犯过一次错：同时改了 7 个 skill 的触发词，结果有些变好了有些变差了，
完全没法判断是哪个改动导致的。从那以后，一次一个，绝不贪多。
❌ 原则一：单一可编辑资产。每次只修改一个文件，避免变量混淆。
示例代码
- 默认使用 Swift 语言
- 示例要精简，只展示关键逻辑，不要写完整的工程代码
- 正反对比（✅ 正确 / ❌ 错误）比单纯的正面示例更有效
文章结构
文件规范
- 每篇文章一个文件夹，文章内容为
README.md
- 图片放在文章文件夹下的
images/ 目录
- 文件夹放在对应分组下：
understanding/（理解 AI）、using/（用好 AI）、coding/（玩转 AI）
标准结构
以下是教程和概念解释类文章的常用结构。不是唯一选择——案例复盘可以用时间线，深度分析可以用「现象 → 解释 → 启示」，产品介绍可以用「问题 → 方案 → 效果」。关键是每篇文章要有清晰的弧线：读者从「不知道」走到「知道了」。
# 标题
> 分组标签（理解 AI / 用好 AI / 玩转 AI）
一句话概括 + 为什么要读这篇。
---
## 一、为什么需要 / 是什么（从痛点或场景切入）
## 二、核心概念 / 工作原理
## 三、怎么用 / 实战示例
## 四、怎么用好 / 关键原则
## 五、小结（表格或金句收束，不写总结性段落）
结构要求
- 开头有钩子，不从定义开始（参考「开头钩子」四种类型）
- 章节之间有自然过渡，不是孤立的知识点堆砌
- 从宏观到微观递进：先建立整体认知，再深入细节
- 具体数字比模糊描述好：「GitHub 35000 星」比「很受欢迎」有力，「5 美元 VPS」比「成本很低」有力
- 末尾用表格做小结，或用一句金句收束。金句的标准：读者读完能记住、能转述
- 如果有后续文章，末尾可加一句预告衔接
内容密度
- 每个观点只讲一次，不要在不同章节重复同一件事
- 表格比长段落好，对比比单面描述好
- 如果一段话删掉后不影响理解，就删掉
- 篇幅参考：概念篇 300-500 行，实践篇可以更长。但有实际价值的内容不要为了控制篇幅而删除，宁可超出也不牺牲深度
- 删除内容前先判断：这段内容是「废话/重复」还是「独立的有价值认知」？前者删，后者留
与其他文章的关系
- 引用项目内已有文章时使用相对链接：
[Prompt](../prompt/)
- 涉及其他概念（如 Rules、Skills、MCP、Agent）时，只做一两句简介，不展开
- 保持每篇文章的主角地位，其他概念是配角
完成后检查清单
