# Article Writing

> 为 ai-essentials 项目写文章、改文章时必须调用。包含强制性的写作风格和结构规范。 TRIGGER when: 用户说写文章、改文章、那篇文章；提到文章主题名+编辑意图（如 RAG 文章、MCP 文章、prompt 那篇、skills 那篇、rules 那篇）；要求对文章加段落、加比喻、改开头、改成表格、调整结构；讨论文章放哪个目录（understanding/ using/ coding/）。关键词：文章、写篇、那篇、开头、小结、章节 + 内容编辑动作。 SKIP: commit message、会议纪要、代码注释、创建 skill、字幕转换、编辑 .claude/rules 配置文件。

- Skill: `iammccc/article-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iammccc/article-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iammccc/article-writing/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: iAmMccc (https://skillmd.com/u/iammccc)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/iammccc/article-writing

---


# 文章写作 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）时，只做一两句简介，不展开
- 保持每篇文章的主角地位，其他概念是配角

## 完成后检查清单

- [ ] 没有 AI 味表述
- [ ] 开头有钩子（反差/结果前置/文化锚点/私人瞬间），不是从定义开始
- [ ] 核心概念有对比对象，不是单面描述
- [ ] 有具体数字和实例支撑观点，不只是抽象论述
- [ ] 推测和事实有明确边界，不混为一谈
- [ ] 代码示例使用 Swift
- [ ] 章节之间有过渡，不是孤立的知识点
- [ ] 没有重复讲同一个观点
- [ ] 小结用表格或金句收束，没有总结性长段落
- [ ] 已更新根目录 README.md 的文章索引