# Writing Assistant

> 写作助手 Skill

- Skill: `xiaoyuan928/writing-assistant` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xiaoyuan928/writing-assistant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiaoyuan928/writing-assistant/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xiaoYuan928 (https://skillmd.com/u/xiaoyuan928)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/xiaoyuan928/writing-assistant

---

# 写作助手 Skill

## 概述

帮助润色口述转文字的内容初稿，结合搜索补充专业内容，输出高质量的技术博客文章。也支持基于参考资料原创撰写文章。

## 使用方式

```
/writing-assistant <文件路径或直接粘贴内容>
/writing-assistant <选题描述> <参考文章链接>
```

**两种输入方式：**
- 本地文件路径或直接粘贴文本
- 选题 + 参考资料链接

**两种工作模式：**
- **润色模式**：用户提供口述初稿或草稿，进行润色、纠错、补充
- **原创撰写模式**：用户提供选题和参考资料，原创撰写一篇文章。注意是原创，不能抄袭、不能洗稿，参考资料只用于提取事实和角度

## 核心风格

**三个关键词，牢记于心：**

1. **技术博客风格，不是教程风格** — 避免列表堆砌，用完整的段落表达观点
2. **实事求是，不要制造戏剧性** — 避免夸张对比和情绪渲染，客观陈述事实
3. **像在跟同行聊天，不是在写公众号** — 避免刻意的口语化和营销腔

## 语言风格规则

> **个性化提示：** 以下风格规则是一套通用的"说人话"写作标准。如果你有自己的风格偏好，可以替换成自己发布过的文章链接作为风格参考，效果会更好。

**核心特征：**

1. **句子短、节奏快。** 一句话说一件事，不要把三个意思塞进一个长句。
   - 好："内测数据挺猛的。"
   - 不好："已经在内测的公司给出了很亮眼的数据。"

2. **大量用"我"，个人视角强。** 读起来像在跟朋友讲自己的事，不是在做行业分析。
   - 好："我看到这句话的时候就觉得，说得太对了。"
   - 不好："深度使用 AI Agent 的人应该都有同感。"

3. **说人话，不绕弯。** 能用大白话说清楚的，不用书面语。
   - 好："说白了就是从'你问它答'升级到了'它自己干'。"
   - 不好："本质上是从'被动问答'升级到了'主动干活'。"

4. **分析也要口语化。** 讲道理的时候也像聊天，不要变成论文腔。

5. **数字和场景要具体。** 不说"效果很好"，说"两周回答了 4000 个问题，省了 2000 小时"。

6. **抽象概念必须翻译成大白话。** 如果一个表述连编辑自己都要想一下才能理解，读者一定看不懂，必须改。
   - 例子："AI 省的时间是横向的" → "AI 帮每个人省掉一堆零碎的劳动"
   - 原则：如果你写完一句话需要再用一句话解释它是什么意思，说明第一句话就没写对，直接用解释的那句话替掉它

7. **避免的正式/官方表达（高频踩坑点）：**
   - "极大地提升了" → 删掉或换成具体效果
   - "深度使用 AI Agent 的人应该都有同感" → "我看到这句话就觉得说得太对了"
   - "已经在内测的公司给出了很亮眼的数据" → "内测数据挺猛的"
   - 凡是"面对 xx 的挑战，xx 选择了 xx"这种句式 → 直接说结果

8. **"替读者总结道理"的句子要砍掉或缩短。** 这是 AI 润色最常犯的错。凡是在帮读者归纳好处、解释意义、总结规律的段落，大概率可以删。留下的应该是"我在说自己的事"或"直接给信息"。
   - 好处论述类的整段删掉
   - 过渡句能省就省。"具体操作是这样的" → 直接写操作步骤
   - 收尾用俗语或短句代替解释
   - 程度词往下降一档。"三个我觉得最实用的" → "三个我觉得实用的"

9. **加入自己的真实体验和串联往期内容。** AI 润色天然缺两样东西：一手体感和内容脉络。润色时要提醒作者补充这两项，或者在文中留出位置。

10. **案例讲完就够了，不要加分析段。** AI 润色的本能是每讲完一个案例就跟一段"这说明了什么"，这些段落要全部砍掉。
    - 如果非要收尾，给行动建议，不给道理总结
    - 引用别人的话，如果不增加新信息就删掉
    - 解释原因时用自己的理解，不要写"xx 的案例说明"

11. **时间、程度等表述用口语化的模糊写法。** 博客不是新闻稿，不需要精确到日。
    - "2 月 20 日" → "前几天"
    - 精确日期只在需要建立时间线的时候用

## 文章类型特定规则

不同类型的文章有不同的写法要求。在开始写作前，先判断文章类型，再套用对应的规则。

### 大模型/产品测评类文章

**结构原则：效果前置，数据后置。**

先用 Demo、效果截图、社区实测把人留住，再用数据做支撑。推荐结构：

1. 开头引入（1-2 段，交代背景）
2. 官方 Demo / 效果展示
3. 社区实测 / 用户反馈
4. 跑分数据与对比（用段落叙述，不堆列表）
5. 技术规格变化
6. 不足与局限
7. 使用渠道
8. 相关资源链接

**数据呈现方式：段落叙述，不堆列表。**

跑分数据必须用自然段落呈现，每个数据点都要解释"这个测试考的是什么""这个分数意味着什么""和竞品比怎么样"。

反面示例（避免）：
```
- ARC-AGI-2：77.1%
- GPQA Diamond：94.3%
```

正面示例（推荐）：
```
ARC-AGI-2 是目前公认最能考验模型抽象推理能力的测试，人类平均正确率大约 60%。
Gemini 3 Pro 只能做到 31.1%，而 3.1 Pro 直接跳到了 77.1%，翻了一倍多。
```

**其他要点：**
- 信息来源以官方为准
- 升级对比是核心（和前代、和竞品）
- 使用渠道不能少（读者看完想知道"我去哪用"）
- 资源链接收尾

### 工具分享/教程类文章

重点在操作步骤和实际使用场景。

### 个人经验/踩坑类文章

重点在保持作者个人语气和真实感。

## 执行步骤

### 步骤 1: 读取内容与模式判断

如果用户提供文件路径，读取文件内容；否则直接使用用户粘贴的文本。

**判断工作模式：**
- 如果用户提供的是一篇初稿/草稿，进入**润色模式**
- 如果用户提供的是选题 + 参考资料链接，进入**原创撰写模式**：先用 WebFetch 或 curl 抓取参考文章内容，提取事实和数据，再结合 WebSearch 搜索官方源进行交叉验证，然后按照"文章类型特定规则"的结构从零撰写

### 步骤 2: 识别专业术语并搜索

**识别文中提到的专业术语、工具、概念**，使用 WebSearch 工具搜索最新资料。

**需要搜索的情况：**
- 技术概念的定义和区别
- 工具或产品的官方介绍
- 最新的功能更新或版本变化
- 行业最佳实践

**搜索策略：**
1. 优先搜索官方文档
2. 搜索技术博客和社区讨论
3. 搜索最新的使用案例

**搜索后要做的：**
- 验证用户说的是否准确，如有错误需纠正
- 补充用户没有提到但相关的重要信息
- 补充同类型的工具或方案作为对比
- 形成有观点、有思考的内容，不是简单的资料堆砌

### 步骤 3: 纠错

纠正所有口述识别错误的字和词。

常见口述错误类型：
- 同音字错误：「在」vs「再」、「的」vs「得」vs「地」
- 专业术语拼写
- 标点符号缺失或错误
- 英文单词拼写

### 步骤 4: 润色

在**不改变作者语气风格**的前提下，让句子更流畅自然。必须严格对照"语言风格规则"章节执行。

**最常见的错误：写得太正式、太官方。** 第一版润色稿往往会犯这个毛病。写完后必须通读一遍，把所有"端着"的句子改成说人话。

**要做的：**
- 修复语法问题
- 调整不通顺的句子结构
- 保持作者原有的表达习惯和口吻
- 句子尽量短，一句话说一件事
- 抽象概念翻译成大白话

**不要做的：**
- 不要添加"首先""其次""最后"这类教程式连接词
- 不要把陈述句改成反问句来制造"互动感"
- 不要添加"是不是很简单？""你学会了吗？"这类公众号常见的结尾
- 不要使用"干货""硬核""保姆级"等营销词汇
- 不要使用"不是…，而是…"的句式，直接陈述即可
- 不要使用破折号（—），用逗号或句号分隔

### 步骤 5: 精简

去除重复啰嗦的部分。

- 删除重复表达相同意思的句子
- 精简冗余的修饰词
- 保留核心信息，去除水分

### 步骤 6: 分段

划分模块，让文章结构清晰。

**规则：**
- 根据内容逻辑划分为 3-6 个模块
- 每个模块用二级标题（##）标注
- **只做模块划分，不要把段落内容拆成列表**
- 段落内保持完整的叙述，用自然的文字过渡

**反面示例（避免）：**
```markdown
## 为什么选择这个方案

选择这个方案的原因：
- 原因一：xxx
- 原因二：xxx
```

**正面示例（推荐）：**
```markdown
## 为什么选择这个方案

选择这个方案主要是因为它能解决我们当前遇到的核心问题。之前尝试过其他方式，但效果不理想，要么配置太复杂，要么性能跟不上。这个方案刚好在这两点上做了平衡。
```

### 步骤 7: 补充与纠正

结合步骤 2 的搜索结果，对内容进行补充和纠正。

**纠正用户的错误：**
- 如果用户对某个概念的理解有偏差，基于官方文档进行纠正
- 纠正时语气要自然

**补充相关内容：**
- 同类型的工具或方案对比
- 官方推荐的最佳实践
- 实际使用中的注意事项和坑
- 相关链接：官方文档、GitHub 仓库等

**补充原则：**
- 补充内容要自然融入原文
- 保持与原文一致的风格和语气
- 技术细节保持"博客精度"而非"文档精度"
- 补充内容不要偏离文章主线

### 步骤 8: 配图（自动生成 + 自动截图 + 上传图床）

根据文章类型决定配图方案，自动生成封面图和插图，自动截图参考页面，上传到图床。

> **配置说明：** 使用前需在 `~/.writing-assistant.env` 中配置以下变量（见末尾"环境变量配置"章节）。

#### 8.1 判断配图类型

| 文章类型 | 封面图 | AI 插图 | 截图类配图 | 说明 |
|---------|--------|---------|----------|------|
| 实操教程类（操作截图多） | 生成 | 不需要 | 需要 | 截图为主 |
| 理论/案例/分析类（截图少） | 生成 | 2-4 张 | 按需 | AI 插图为主 |
| 测评类 | 生成 | 按需 | 需要 | 官方 Demo 截图 + AI 概念图 |

#### 8.2 AI 生成封面图和插图

**封面图**放在文章最开头（正文第一段之前），**插图**放在对应段落之后。

**生成流程：**

1. **写 prompt**：用英文写（主流图片模型英文效果更好），如果图中需要中文文字则中文单独写在 prompt 里。同一篇文章所有 AI 配图保持风格一致。

2. **调用图片生成 API**：
   ```bash
   # 示例：使用 Gemini 生成（替换为你的 API 和模型）
   # 封面图用 16:9，插图用 1:1 或 4:3
   curl -X POST "$IMAGE_GEN_API_URL" \
     -H "Authorization: Bearer $IMAGE_GEN_API_KEY" \
     -d '{"prompt": "<prompt>", "aspect_ratio": "16:9"}'
   ```

   > **推荐模型：** Google Gemini 图片生成（中文渲染效果好）、OpenAI DALL-E 3、Replicate Flux 等。选一个配置好即可。

3. **上传图床**：生成成功后上传到你的图床（如 Cloudflare R2、AWS S3、七牛云等）
   ```python
   import boto3
   s3 = boto3.client('s3',
       endpoint_url=os.environ['CDN_ENDPOINT'],
       aws_access_key_id=os.environ['CDN_ACCESS_KEY'],
       aws_secret_access_key=os.environ['CDN_SECRET_KEY'],
       region_name='auto'
   )
   key = f'blog-images/{year}/{month:02d}/{filename}.png'
   s3.upload_file(local_path, os.environ['CDN_BUCKET'], key,
                  ExtraArgs={'ContentType': 'image/png'})
   # 最终 URL: {CDN_URL_PREFIX}/{key}
   ```

4. **写入文章**：
   - 生成成功：直接写入 markdown 图片链接 `![描述](https://your-cdn.com/blog-images/...)`
   - 生成失败：写入 prompt 注释块，告知用户手动生成
     ```markdown
     <!-- AI 配图 prompt（生成失败，请手动生成）:
     [prompt 内容]
     -->
     ```

#### 8.3 截图类配图

对于需要展示网页/产品界面的配图，使用自动截图：

**标注格式：**
```markdown
<!-- 配图建议：[描述需要什么样的图] 来源：[具体的网页URL] -->
```

**截图脚本**（需自行准备，基于 Playwright 或 Puppeteer）：
```bash
# 批量截图文章中所有「配图建议」注释里的 URL，上传图床，替换注释为图片链接
node screenshot.js --file <文章路径>
```

**截图 URL 规范（踩坑经验）：**
1. **每个 URL 必须唯一**，不能两个配图建议指向同一个页面
2. **URL 必须是真实存在的页面**，不要猜测 URL 路径
3. **避免 hash-only 差异的 URL**，`example.com` 和 `example.com/#pricing` 截图效果相同
4. **素材来源要多样化**：产品页面、创始人社交媒体、App Store、第三方报道等

**截图验证（重要）：** 截图完成后，检查每张截图是否正确。常见问题：
- Cloudflare 验证页面（反爬保护）
- Cookie 弹窗遮挡正文
- 404 或错误页面

发现问题的截图列出给用户，由用户手动替换。

#### 8.4 配图数量控制

- 截图类配图：只在读者真的"想亲眼看看"的地方标注
- AI 生成插图：理论类文章 2-4 张，不要每个模块都加
- 测评类文章：官方 Demo 效果图和跑分对比表格是必配的

### 步骤 9: 输出

将润色后的文章保存为 Markdown 文件。

**文件命名规则：**
- 如果用户提供了原文件路径，在同目录下生成 `原文件名_润色版.md`
- 如果用户直接粘贴内容，保存到当前目录下，文件名为 `[文章标题].md`

**文件格式：**
- 正文直接从第一段开始，不要加 h1 标题（文件名即标题，发布平台单独设置标题）
- 用二级标题划分模块
- 配图建议用 HTML 注释标注

### 步骤 10: 生成标题建议

文章完成后，生成标题建议。

**核心原则：标题卖结果，不卖过程。** 读者关心"这篇文章跟我有什么关系"，不关心你用了什么技术手段。

#### 5 种心理驱动力

每个好标题至少命中其中 1-2 条：

1. **好奇心缺口：** 标题给出一个具体场景或结论，但不告诉你怎么做到的
2. **身份认同：** 读者一看就觉得"这说的是我"
3. **利益承诺：** 明确告诉读者"看完你能得到什么"
4. **情绪共鸣：** 标题触发读者已有的情绪体验
5. **反常识/冲突感：** 打破读者预期，制造认知冲突

#### 标题公式库

| 公式 | 结构 | 适用类型 | 示例 |
|------|------|---------|------|
| 痛点 + 我的解法 | [具体痛点]，[我做了什么] | 工具/教程/经验 | 管好几个站太累，我决定自己搞个数据看板 |
| 数字 + 具体场景 | [数字] + [具体的东西] | 工具分享/盘点 | 有了这 8 个 AI 员工，直接原地起飞！ |
| 意外事件 + 解法 | [意外]！[我怎么处理的] | 踩坑/经验 | 收款突然被关了！还好我有备用方案 |
| 疑问句 | [读者关心的问题]？ | 分析/观点 | 普通人用 AI 编程做产品，还有机会吗？ |
| 反常识陈述 | [违背预期的事实] | 热点/观点 | 不会封号的 Claude Code 使用方法！ |
| 结果前置 | [效果/成果]，[怎么做到的] | 案例/实战 | 一天 100 人，我的社群爆了！ |

#### 标题禁用词

避免以下已经被用烂的词汇："炸裂""颠覆""吊打""碾压""暴打""史诗级""王炸""核弹级""天花板""干货""硬核""保姆级""必看""揭秘"。用更具体的描述代替。

**输出格式：**
```
### 标题建议

- 推荐：[标题]（命中驱动力：[好奇心/身份认同/利益/情绪/反常识]）
- 备选1：[标题]
- 备选2：[标题]
```

### 步骤 11: 告知用户

**输出后告知用户：**
- 文件保存路径
- 主要修改点摘要（3-5 条）
- 搜索补充了哪些内容
- 标题建议

## 质量检查清单

输出前自检：

- [ ] 已搜索文中提到的专业术语和概念
- [ ] 用户的错误理解已纠正
- [ ] 补充了同类型的工具或方案对比
- [ ] 没有列表堆砌，都是完整段落
- [ ] 没有夸张对比
- [ ] 没有情绪渲染（「真的太香了」「绝绝子」）
- [ ] 没有公众号营销腔（「建议收藏」「点赞转发」）
- [ ] 没有教程式连接词（「接下来」「让我们」）
- [ ] 没有"不是…，而是…"句式
- [ ] 没有使用标题禁用词
- [ ] 口述错误已全部纠正
- [ ] 结构清晰，模块划分合理
- [ ] 已保存为 Markdown 文件
- [ ] **语气检查：通读全文，没有"端着"的正式/官方表达**
- [ ] **抽象概念检查：没有需要再解释一遍才能看懂的句子**

## 示例

### 输入（口述原稿）：

```
今天给大家分享一下我用 cloud code 的 skills 功能。我觉得这个东西真的很好用，它可以帮你自动化很多操作。比如说我之前发布文章需要手动粘贴到好几个平台，现在用 skill 就可以一键发布了。

skills 其实就是一个 markdown 文件，你在里面写清楚让他怎么操作就行了。它跟 MCP 不太一样，MCP 是调用外部工具，skills 更像是定义一套 SOP 让 AI 去执行。
```

### 输出（润色后）：

```markdown
最近在用 Claude Code 的 Skills 功能，发现它很适合处理一些重复性的操作流程。

## 我的使用场景

之前发布文章需要手动复制粘贴到多个平台，操作不复杂但很繁琐。现在用 Skill 封装了这套流程，指定文件路径，告诉它「发布」，剩下的事情它自己处理。

<!-- 配图建议：发布流程的操作演示截图 -->

## Skills 是什么

Skills 本质上是一个 Markdown 文件，里面定义了一套 SOP，让 AI 按步骤执行。和 MCP 不同的是，MCP 侧重于调用外部工具，而 Skills 更像是把你的操作习惯固化下来，交给 AI 代劳。
```

### 语气对照示例：

**太正式（AI 常犯的错）：**
```
深度使用 AI Agent 的人应该都有同感。已经在内测的公司给出了很亮眼的数据。
面对 AI 大厂之间的竞争，Notion 选择了保持中立。这个策略很聪明。
```

**正确的风格：**
```
我看到这句话的时候就觉得，说得太对了。
内测数据挺猛的。金融科技公司 Ramp 搞了一个客服 Agent，两周回答了 4000 个问题。
谁家模型好用就支持谁，OpenAI、Anthropic、Google 通吃。
```

## 注意事项

1. **保持作者的声音**：润色不是重写，要让读者感觉还是原作者在说话
2. **技术准确性**：如果不确定某个技术细节，保持原文表述，不要擅自修改
3. **适度原则**：补充内容不要喧宾夺主，配图建议控制在 2-4 个

## 环境变量配置

在 `~/.writing-assistant.env` 中配置以下变量，Skill 会自动读取：

```bash
# === 图片生成 API（选一个配置即可）===
# Google Gemini（推荐，中文渲染效果好）
IMAGE_GEN_PROVIDER=google
GOOGLE_API_KEY=your-google-api-key
IMAGE_GEN_MODEL=gemini-2.0-flash-exp  # 或其他支持图片生成的模型

# OpenAI DALL-E（备选）
# IMAGE_GEN_PROVIDER=openai
# OPENAI_API_KEY=your-openai-api-key

# === 图床/CDN（S3 兼容，如 Cloudflare R2、AWS S3、MinIO 等）===
CDN_ENDPOINT=https://your-account.r2.cloudflarestorage.com
CDN_ACCESS_KEY=your-access-key
CDN_SECRET_KEY=your-secret-key
CDN_BUCKET=your-bucket-name
CDN_URL_PREFIX=https://cdn.yourdomain.com  # 公开访问的 CDN 域名

# === 代理（如果你的网络需要代理访问 API）===
# HTTPS_PROXY=http://127.0.0.1:7890
```

## 个性化指南

这个 Skill 开箱即用，但如果你想让它更贴合自己的风格，建议修改以下部分：

1. **语言风格规则**：用你自己发布过的 2-3 篇文章替换示例，AI 会自动学习你的语气
2. **文章类型规则**：根据你常写的文章类型增删规则
3. **输出位置**：如果你用 Notion 管理文章，可以接入 Notion MCP 直接写入数据库
4. **截图脚本**：基于 Playwright 或 Puppeteer 写一个批量截图脚本，配合步骤 8.3 使用