| name | write-tech-article |
| description | Use when the user wants to write a new technical blog article or edit/revise an existing one. Triggers on requests like "write an article about X", "write a blog post on X", "help me revise this article", "polish this blog post", or when given a GitHub URL and asked to write about it. |
写技术文章
概述
以用户固有的个人风格撰写技术博客文章，内容涵盖 GitHub 项目、技术话题或本地代码项目。输出为 Hexo 格式的 Markdown 文件，保存至 ~/ayou/blog/source/_posts/。
正式动笔前，必须先确认大纲。
工作流程
新文章：
1. 分析输入
2. 提炼亮点
3. 生成大纲 → 等待用户确认
4. 撰写全文
5. 保存到博客
修改已有文章：
1. 读取现有文章文件
2. 理解用户的修改意图
3. 直接修改（无需确认大纲）
4. 保存更新后的文件
第一步：分析输入
判断输入类型并收集信息：
- GitHub URL — 使用
gh repo view <owner/repo> 或 WebFetch 读取 README、仓库结构、关键源文件、Star 数及使用示例
- 技术话题 — 使用 WebSearch 收集核心概念、使用场景和实际案例
- 本地目录 — 使用当前工作目录；读取 README、package.json/Cargo.toml 及关键源文件
第二步：提炼亮点
识别：
- 该项目/技术解决的核心问题
- 2–3 个最有意思的切入角度（架构、用法、演示、源码剖析）
- 文章类型：工具介绍型 / 源码解析型 / 实战教程型
第三步：生成大纲（等待用户确认）
向用户展示：
- 建议标题
- 每个章节标题 + 一句话描述
- 建议的标签/分类
在用户确认或修改大纲之前，不得撰写全文。
第四步：撰写全文
遵循下方所有写作规范。需要截图的地方使用图片占位符，如 。
第五步：保存到博客
- 选择简短的英文/拼音 slug（如
ai-langgraph.md、react-suspense.md）
- 将完整文件写入
~/ayou/blog/source/_posts/<slug>.md
- 告知用户文件路径
写作风格
结构
| 文章长度 | 章节风格 |
|---|
| 长篇（5 节以上） | # 一、标题、# 二、标题；小节用 ## 1.1 |
| 短篇（2–4 节） | 普通标题：# 实现方式、# 总结 |
始终以 # 前言 开头——交代背景、描述痛点、说明为什么值得关注。
语气
- 口语化、有代入感："浅玩一下"、"接下来我们体验一下"、"简直赢麻了"
- 先抛出问题或疑问，再揭晓答案——不要一上来就说结论
- 用
**加粗** 标注关键术语和结构性重点
去 AI 味（写作时始终遵守）
写完初稿后，必须逐条检查以下规则并修正，确保文章读起来像人写的。
核心原则
- 删除填充短语：去除"值得注意的是""为了实现这一目标"等拐杖词，直接说事
- 打破公式结构：避免二元对比（"不仅……而且"）、戏剧性分段、修辞性设置
- 变化节奏：混合句子长度，短句有力，长句展开细节。两项并列优于三项
- 信任读者：直接陈述，跳过软化和过度解释
- 删除金句：如果一句话听起来像名人名言或总结性标语，重写它
必须避免的模式
AI 高频词汇（禁用）： 此外、至关重要、深入探讨、增强、培养、格局（抽象名词）、关键性的、展示、证明（夸大用法）、充满活力的、宝贵的、不断演变的
三段式法则： 不要强行凑三项并列。"可以自由组合、按需加载、独立维护"→ 改为两项或用段落叙述
否定式排比： "这不仅仅是 X，而是 Y" → 直接说 Y 是什么
宣传性收尾： "关键一步""真正的封装单元""标志着一个转变" → 用具体事实或动作替代
破折号过度使用： 一段最多一个破折号。多了换成句号或逗号
粗体过度使用： 粗体只用于关键术语首次出现和结构性标题，不要把整句话加粗
模糊归因： "业界普遍认为""专家表示" → 给出具体来源或删除
通用积极结论： "未来可期""前景光明" → 用具体的下一步或事实收尾
同义词循环： 不要为了避免重复而刻意换词（"项目""工程""方案"交替指代同一个东西），同一个概念就用同一个词
自检清单（交稿前过一遍）
- 连续三个句子长度相同？打断其中一个
- 段落结尾都是总结句？变换结尾方式
- 用了"此外""然而"等连接词？考虑删除
- 三项并列？改为两项或四项
- 结尾像是在写"展望未来"？改成具体的事实或建议
内容规范
- 有演示效果或结果图时：在对应章节开头写"先上效果" + 图片占位符
- GitHub 项目：始终链接到具体的 tag 或 commit，如
[v1](https://github.com/owner/repo/tree/v1)
- 代码块：始终加语言标识符（
```typescript、```bash、```python）
- 图片：本地相对路径
./article-slug/N.png，仅使用 PNG 或 JPG 格式（不用 SVG、WebP 等）；需要示意图或流程图时，由 Claude 直接绘制并保存为图片文件，不要使用 bash 命令生成图片，也不要留占位符
- 流程图/架构图规范：连接线不得穿越任何节点框体，必须沿框体外侧绕行；线上的标注文字不得覆盖任何框体，需留出间距；同一系列文章的配图应保持统一的配色、形状和排版风格（参考
source/_posts/ai-agent-skill/flow.png 的视觉基准）
- SVG 转 PNG/JPG：使用
node ~/.claude/skills/write-tech-article/svg-to-image.js <file.svg> [png|jpg] [width]；依赖 sharp（优先）或 playwright，首次使用需安装（npm install sharp）
- 文字要精简：能一句话说清楚的不要用两句，能删的段落就删。现在的读者没耐心看大段文字，宁可多用代码、表格、示例来表达，少写解释性的长段落
- 先说"为什么"，再说"怎么做"——不要只堆代码，先给出背景
- 段落和章节之间要有自然的衔接过渡，每个章节应顺势引出下一节，避免生硬跳转
- 概念引入必须有铺垫：新概念（变量名、术语、模块名）第一次出现时，必须从读者已知的问题或场景切入，再自然引出概念作为解答。禁止直接抛出一个读者没见过的名词然后再解释它是什么。正确做法：先提出问题（如"消息来了，怎么知道属于哪个对话？"），再引出概念（如 routingKey）作为解决方案
- 事实必须可验证：不要为了叙事效果虚构"最初的做法""早期版本"等历史。如果确实经历过某个阶段，应能在 git 历史或代码中找到依据。如果没有，直接阐述设计要解决的问题，不要编造演化过程
- 章节顺序遵循依赖关系：如果 B 概念依赖 A 概念，A 必须先于 B 出现。写完后检查：每个概念第一次被使用时，读者是否已经知道它是什么
总结怎么写
总结的作用是让读者回忆起刚才读了什么，不是反思或展望。
基本原则：
- 开头用一句话点明这篇文章覆盖的问题域，如"这篇讲了 X 和 Y 两个问题"
- 每个主要话题一句话，说清解决思路，不展开细节
- 系列文章：最后一句交代下篇方向，一句即可
- 总长度：3–5 句，不超过这个范围
示例（概念级，合格）：
这篇讲了数字团队的两个基础问题：角色怎么定义，以及角色之间怎么通信。
角色定义靠 workspace 四件套——四个文件写清楚 Agent 是谁、做什么、不该碰什么。框架代码完全无感，换一个目录就换一个角色。
通信靠共享工作区加邮箱状态机。邮箱用三态解决了消息可靠性问题，reset-stale 处理崩溃恢复。
下一篇加调度器，不再需要人来串联。
示例（技术细节过多，不合格）：
本文介绍了 soul.md / agent.md / user.md / memory.md 四件套加载机制，以及 unread → in_progress → done 三态状态机的实现，包括 read() 原子操作和 reset-stale 超时恢复逻辑。
Frontmatter 模板
---
title: 文章标题
date: YYYY-MM-DD HH:MM:SS
tags:
- tag1
- tag2
categories:
- 分类
description: 一句话描述，用于 SEO 和文章摘要
---
现有文章的常见标签/分类规律：
- AI 工具类：标签
ai、agent；分类 ai
- 源码系列：标签对应技术栈（如
wasm、react）；分类为语言（如 rust）
- 算法类：标签
algorithm；分类 algorithm
- 前端类：标签对应框架；分类
frontend
Demo 运行
当文章需要运行 demo 来验证效果或截图时：
- 将 demo 项目放在
./demo 目录下
- 前端项目统一使用 pnpm 作为包管理器（安装依赖用
pnpm install，启动用 pnpm dev 等）
常见错误
| 错误 | 修正 |
|---|
| 未确认大纲就开始写全文 | 始终展示大纲并等待确认 |
| 前言空泛，没有明确的痛点 | 用具体场景或问题开头 |
| 代码块没有语言标识符 | 三个反引号后必须加语言 |
Frontmatter 缺少 description 字段 | 必填——写一句简洁的摘要 |
| 文件名使用中文 | 只能使用英文/拼音 slug |
