content-forge/.claude/skills/write-article/SKILL.md

---
name: write-article
description: >
  Generate articles from Obsidian vault topics, optimized for traffic pool entry
  (click-through × dwell time × completion rate). Output: a publish-ready draft
  in 02-drafts/ with complete frontmatter, passing 27-item quality gate
  (material density + title + de-AI + completion rate).

  USE WHEN: User wants to create new long-form content (tech blog, opinion piece,
  tutorial, social post, lizi_kk-style article) from a structured topic in 01-topics/.
  Trigger phrases: 写文章、写作、生成草稿、技术博客、观点文、教程、社交短文、
  article、blog post、draft、人格写作、栗子KK风格。

  DON'T USE WHEN:
  - User wants to analyze/deconstruct existing content → use dao-analysis instead.
  - User wants to review/critique an existing draft → use multi-review or /review instead.
  - User wants to import an external draft into vault → use import-draft instead.
  - User wants to load vault context → use my-world instead.
  - User wants to edit an existing draft in 02-drafts/ → use obsidian CLI directly.
  - User says "分析"、"拆解"、"审查"、"导入" without creation intent → not this skill.
---

# Write-Article：Obsidian 文章写作技能

## 目标

用统一流程产出**能进流量池**的可发布草稿。

核心公式：**点击率 × 停留时长 × 完读率 = 流量池入场券**。三项相乘，任一项为零则全盘归零。详见 `references/content-quality.md`。

质量底线：
- 标题：候选 ≥5 个，评分 ≥18/25
- 去 AI 味：零容忍黑名单词汇，人味注入 ≥5 项
- 完读率：Hook 前 3 句到位，段间钩子不断，结尾金句+CTA

## 路由规则（Use when / Don't use when）

Use this skill when:
- User wants to **create new content** from a topic brief in `01-topics/`
- User says "写文章"、"生成草稿"、"write an article"、"create a draft"
- User specifies a style (tech_blog, opinion, tutorial, social_short, lizi_kk)
- User provides source notes and wants a publish-ready draft

Do NOT use this skill when:
- User wants to **analyze** existing content (article, transcript, concept) → use `dao-analysis`
- User wants to **review/critique** a draft for quality → use `multi-review` or `/review` command
- User wants to **import** an external draft into the vault → use `import-draft`
- User wants to **load vault context** or see what's in the vault → use `my-world`
- User wants to **edit** an existing draft (fix typos, update sections) → use `obsidian` CLI directly
- User wants to **format** a draft for publishing → use `format-markdown` (baoyu skill)

Edge cases:
- "帮我把这篇笔记改写成文章" → **this skill** (creation from notes = write-article)
- "分析一下这篇文章为什么火" → **not this skill** (analysis = dao-analysis)
- "审查我的草稿" → **not this skill** (review = multi-review)
- "把 atomstorm 项目里的文章导入 vault" → **not this skill** (import = import-draft)

## 输入要求

必须提供：
- `topic`：文章主题（1 句话）
- `style`：`tech_blog` | `opinion` | `tutorial` | `social_short` | `lizi_kk`
- `audience`：目标读者
- `source_notes`：至少 1 个 Obsidian note 路径（vault 相对路径）
- `tags`：1-5 个标签

可选：
- `persona`：人格激活（`栗子KK`），深度扮演作者身份
- `intensity`：人格强度 `light` | `medium` | `heavy`（默认 medium）
- `title`：文章标题（如未提供，Step 3 强制生成候选）
- `slug`：文件 slug（英文短横线）
- `length_target`：目标字数或段落数
- `cta`：结尾行动建议
- `publish_channel`：发布渠道
- `material_sources`：额外素材文件路径列表（vault 相对路径），用于补充素材锚点

> **风格与人格联动**：当 `style: lizi_kk` 时，自动加载 vault 内 `templates/author-style-lizi-kk.md` 和 `personal-context/` 参考文章，无需额外指定参数。

**`style` 与 `persona` 交互矩阵**：

| 组合 | 行为 |
|------|------|
| `style: lizi_kk` 无 `persona` | 仅应用风格模板（结构+语言特征），不深度扮演 |
| `persona: 栗子KK` 无 `style: lizi_kk` | 人格口吻叠加到所选风格上（如 tech_blog + 栗子KK 语气） |
| 两者都设置 | 完整集成：风格模板 + 人格深度扮演（推荐） |

## 强制工作流（7 步，不得跳步）

### Step 1a：读取素材

逐个读取 `source_notes` 中的笔记，并搜索 vault 中相关素材，确认事实边界。

```bash
# 必须先 cd 到 vault 目录（CLAUDE.md §6.1 强制要求）
cd "${VAULT_PATH:-/home/kang/apps/content-forge/content-forge}"

# 读取指定源笔记
obsidian read path="<source_note_path_1>"
obsidian read path="<source_note_path_2>"

# 搜索 vault 中相关素材（关键词来自 topic）
obsidian search query="<topic关键词>"

# 读取匹配的 personal-context/ 文章（亲历锚点来源）
obsidian read path="personal-context/<matching_article>.md"

# 读取匹配的 09-viral-examples/ 案例（案例/数据锚点来源）
obsidian read path="09-viral-examples/<matching_example>.md"

# 读取用户额外指定的素材（如有 material_sources 参数）
obsidian read path="<material_source_path>"
```

执行要求：
- `source_notes` 中每个路径都要读取。
- 主动搜索 vault 中与 topic 相关的素材（`personal-context/`、`00-inbox/`、`09-viral-examples/`）。
- 未读完素材前，禁止进入写作。
- 素材来源优先级见 `references/material-anchors.md` §2。

### Step 1b：提取素材锚点

从 Step 1a 读取的所有素材中，提取四类素材锚点并输出素材脚手架。

详细规则见 `references/material-anchors.md`。核心约束：

- **总锚点 ≥3**，**Type A（亲历）≥1**，**Type B 或 C（数据/案例）≥1**
- 必须输出结构化素材脚手架（格式见 `references/material-anchors.md` §3）
- 素材不足时输出 `[?] 素材不足：缺少 <具体类型>`，**禁止进入 Step 2**

输出格式：
```
## 素材脚手架

### Type A 亲历锚点
1. [锚点描述] — 来源: [vault路径]
...

### Type B 数据锚点
1. [数据 + 来源归属] — 来源: [vault路径或URL]
...

### Type C 案例锚点
1. [命名实体 + 分析要点] — 来源: [vault路径或URL]
...

### Type D 观察锚点
1. [引用/对话 + 归属] — 来源: [vault路径]
...

### 统计
- 总锚点: X 个
- Type A: X 个 ✓/✗（≥1）
- Type B|C: X 个 ✓/✗（≥1）
- 判定: 通过 / [?] 素材不足
```

### Step 2：激活人格（可选）

如果提供了 `persona` 参数，按 `references/personas.md` 激活对应人格。

**激活确认格式**：
```
收到，创作者。'栗子KK' 人格已上线（强度：medium）。

> 风格预览：说实话，这个坑我踩了不下10次，今天终于有空聊聊。

等待您的创作指令。
```

**人格参数**：
- `persona`: 人格名称（目前支持 `栗子KK`）
- `intensity`: `light` | `medium` | `heavy`（默认 medium）

### Step 3：标题工程

标题决定 80% 的点击率。**禁止只写一个标题直接用。**

完整流程见 `references/content-quality.md` §1。核心约束：

- 生成 **≥5 个候选标题**，覆盖不同公式（经历+数字+痛点 / 成本+悬念+真相 / 反常识 / 99%+反差 / 身份锚定）
- 每个候选命中**五要素 ≥3 项**（第一人称"我"、具体数字、张力词、信息缺口、身份锚定）
- **评分 ≥18/25**（5 维度 × 1-5 分：好奇心缺口、情绪冲击、身份共鸣、具体度、可信度）
- 标题 **≤35 字**（微信折叠阈值）
- 禁止学术腔、泛泛而谈、标题党

输出格式：
```
候选标题：
1. [标题] — 评分: XX/25 — 命中要素: [列表]
2. [标题] — 评分: XX/25 — 命中要素: [列表]
...

✦ 最终选定: [标题]（原因: ...）
```

### Step 4：生成文章草稿

按 `references/writing-styles.md` 选择对应风格模板生成正文。
如果激活了人格，同时应用 `references/personas.md` 的人格设定。

**素材先行原则**（详见 `references/material-anchors.md` §4）：
- 正文必须围绕 Step 1b 的素材脚手架构建，每个主要论点必须锚定到具体素材。
- Hook 第 1 句必须直接包含 ≥1 素材锚点（优先 Type A 或 Type B）。不是"前 3 句"，是"第 1 句"——铺垫后置。
- 每个主要章节（H2/编号段落）至少引用 ≥1 个锚点。
- 结尾回扣开头锚点，形成首尾呼应。
- 所有事实性断言必须追溯到素材锚点，或标记 `[?]` 待验证。

**风格联动规则**：
- 当 `style: lizi_kk` 时，必须额外通过 `obsidian read path="templates/author-style-lizi-kk.md"` 读取风格指南，并参考 `personal-context/` 目录的已发表文章（这些文件位于 vault 内，需在 vault 目录下执行 CLI）。

#### 4a. 去 AI 味（强制）

详细规则见 `references/content-quality.md` §2。核心执行项：

- **黑名单零容忍**：开头/过渡/结尾废话出现即重写（完整黑名单见 §2.1）
- **意义膨胀零容忍**：删除"里程碑意义"、"划时代"、"引领新范式"等空洞修饰（§2.1）
- **模糊引用零容忍**：所有"研究表明"、"业内人士"必须给出具体来源，否则删除（§2.1）
- **打破 AI 结构**：段落长短交替（每连续 3 段必须有 ≥1 段 ≤2 句话）、打破对称、语气变化、偶尔不完整句、禁止绕路表述（§2.2）
- **禁止抽象过度**：每个抽象观点后必须紧跟一个具体场景（含时间/地点/数字/工具名），禁止连续两个以上的纯观点段落（§2.2）
- **禁止聚合清单**：禁止在结尾或独立章节使用"我的N个思考/感悟/总结"式编号列表，洞察必须散布在正文中（§2.2）
- **人味注入 ≥5 项**：不规则段落、口语化、括号吐槽、具体数字、个人经历、反问句、混合情绪、刻意凌乱等（完整清单 12 项见 §2.3）
- **二次审计**：门禁检查后，通读全文自问"哪里一眼看出 AI 写的"→列出→修复（§2.4）

#### 4b. 完读率优化（强制）

详细规则见 `references/content-quality.md` §3。核心执行项：

- **前 3 句 Hook**：反直觉结论 / 真金白银 / 身份挑战 / 悬念制造（禁止背景介绍、自我介绍、目录式开头）
- **段间钩子**：每个 section 尾部制造"未完成感"
- **小标题有信息量**：不是"第一步"而是"第一步：这个操作让90%的人栽跟头"
- **阅读节奏**：每 300-500 字视觉断点，每连续 3 段必须有 ≥1 段 ≤2 句话，代码块 ≤15 行
- **结尾工程**：回扣开头 + 金句 + 具体 CTA

执行要求：
- 只使用已读取素材中的事实。
- 观点必须有论证链，不得堆砌口号。
- 内容结构必须匹配所选风格的"结构"要求。
- 人格激活时，口吻必须符合人格的 `voice_signature` 和 `catchphrases`。

### Step 5：创建草稿文件

将 frontmatter + 正文一次性写入 `02-drafts/` 目录，减少 CLI 调用开销。

```bash
obsidian create path="02-drafts/<YYYY-MM-DD>-<slug>.md" content="---
id: '<YYYY-MM-DD>-<slug>'
title: '<title>'
slug: '<slug>'
status: draft
content_type: article
channels:
  - wechat
  - x
language: zh-CN
source_urls: []
assets: []
cover_image: ''
template: article
owner: content-forge
created_at: '<YYYY-MM-DD>T00:00:00+08:00'
updated_at: '<YYYY-MM-DD>T00:00:00+08:00'
style: '<style>'
audience: '<audience>'
tags:
  - '<tag1>'
  - '<tag2>'
source_notes:
  - '<note1.md>'
---

<ARTICLE_BODY>"
```

执行要求：
- 目标目录必须是 `02-drafts/`。
- 文件名必须包含日期前缀与 slug。
- frontmatter 必填字段对齐 CLAUDE.md §4.2（id, title, slug, status, content_type, channels, language, source_urls, assets, cover_image, template, owner, created_at, updated_at）。
- 正文必须是 Markdown，可直接发布或二次编辑。

### Step 6：验证 frontmatter

创建完成后，回读文件确认 frontmatter 完整性。

```bash
obsidian read path="02-drafts/<YYYY-MM-DD>-<slug>.md"
```

如果回读发现 frontmatter 字段缺失或格式异常，使用 `property:set` 逐项修补：

```bash
obsidian property:set path="02-drafts/<YYYY-MM-DD>-<slug>.md" name="<field>" value="<value>"
```

必填字段检查清单（对齐 CLAUDE.md §4.2）：
- `id`, `title`, `slug`, `status`, `content_type`, `channels`, `language`
- `source_urls`, `assets`, `cover_image`, `template`, `owner`
- `created_at`, `updated_at`

### Step 7：质量检查

逐项验证并输出 `[✓]` 或 `[✗]`，**任一项 `[✗]` 时停止交付并修复**。

完整门禁清单见 `references/content-quality.md` §4。

#### 基础门禁

- [ ] 所有 `source_notes` 已执行 `obsidian read`
- [ ] 草稿已通过 `obsidian create` 写入 `02-drafts/`
- [ ] frontmatter 必填字段完整（Step 6 回读验证通过）
- [ ] 不存在事实捏造与无依据断言

#### 标题门禁（§4.1）

- [ ] 候选标题 ≥5 个
- [ ] 最终标题评分 ≥18/25，命中五要素 ≥3 项
- [ ] 标题 ≤35 字

#### 去 AI 味门禁（§4.2）

- [ ] 前 50 字无黑名单词汇
- [ ] 无"首先...其次...最后"四段式
- [ ] 结尾无"综上所述/希望有帮助"
- [ ] 无意义膨胀词汇（"里程碑意义"、"划时代"、"深远影响"）
- [ ] 无模糊引用（"业内人士表示"、"研究表明"须给出处）
- [ ] 相邻段落字数差异 >20%（至少 3 组）
- [ ] 人味注入清单命中 ≥5 项（含混合情绪/刻意凌乱）
- [ ] 二次审计通过（自问"哪里一眼看出AI"→ 无残留）

#### 完读率门禁（§4.3）

- [ ] 前 3 句完成 Hook
- [ ] 每个 section 尾部有段间钩子
- [ ] 小标题有信息量
- [ ] 每 300-500 字有视觉断点
- [ ] 结尾有金句 + 具体 CTA
- [ ] 全文无超过 15 行的代码块

#### 素材密度门禁（§4.4）

- [ ] 素材脚手架已在 Step 1b 输出，总锚点 ≥3
- [ ] 亲历锚点（Type A）≥1
- [ ] 数据/案例锚点（Type B/C）≥1
- [ ] 第 1 句包含 ≥1 素材锚点（非标题，正文首句）
- [ ] 每个主要章节引用 ≥1 锚点
- [ ] 无未标注来源的事实性断言（或已标 `[?]`）

## 输出约束

- 输出仅包含文章草稿及必要元数据，不输出无关解释。
- 文章语言默认中文，除非用户显式要求其他语言。
- 禁止编造数据、案例、引文、实验结果。
- 未确认的事实必须标记 `[?]`，并明确缺失项。
- 结构必须符合所选风格规范（见 `references/writing-styles.md`）。
- 段落应可读，避免空泛套话与重复表达。

## 失败处理

- 缺少必要输入时，返回：`[?] 缺失输入：<字段名>`，并停止写入。
- `obsidian` 命令失败时，返回：`[✗] <命令> 失败：<错误信息>`，并停止后续步骤。
- 如果无法确定风格，默认使用 `tech_blog`，同时显式告知用户。

## 风格参考

- `references/material-anchors.md` — 素材锚点规范（四类锚点 + 脚手架 + 编织规则）
- `references/content-quality.md` — 流量池质量框架（标题工程 + 去AI味 + 完读率 + 素材密度）
- `references/writing-styles.md` — 5 种写作风格模板
- `references/personas.md` — 人格化配置（栗子KK）
- vault 内 `templates/author-style-lizi-kk.md` — 栗子KK 详细风格指南（通过 `obsidian read` 读取）
- vault 内 `personal-context/` — 已发表文章参考（5 篇）