博客文章撰写技能

博客文章撰写技能 是做什么的？

根据代码变更、营销简报或功能描述撰写高质量博客文章。处理 SEO、结构、语气匹配和视觉内容。

写作规则（不可协商）：绝不使用长破折号（—）或短破折号（–）。请改用连字符 -。 适用于生成的每一行文案。

输入解析

按以下顺序解析参数（如果有的话）：

1. 指向现有营销简报文件的路径（包含“执行摘要”或“关键信息”的 .md 文件）→ 营销简报
2. 匹配 GitHub URL 或 #\d+ 模式 → PR
3. 包含 ... 或 .. → git 引用范围
4. 解析为现有文件/目录 → 代码库功能
5. 否则 → 自由格式文本

如果没有提供参数，请询问：“我应该写什么？你可以提供营销简报路径、PR URL/编号、git 引用范围（例如 v1.0...v2.0）、文件/目录路径，或者直接描述主题。”

如果多个解释匹配，请与用户确认。

流程

digraph blog_post {
    rankdir=TB;
    “解析输入” [shape=box];
    “阶段 1：发现” [shape=box];
    “阶段 2：研究” [shape=box];
    “阶段 3：配置” [shape=box];
    “阶段 4：提纲” [shape=box];
    “提纲已批准？” [shape=diamond];
    “阶段 5：写作” [shape=box];
    “阶段 6：输出” [shape=box];

    “解析输入” -> “阶段 1：发现”;
    “阶段 1：发现” -> “阶段 2：研究”;
    “阶段 2：研究” -> “阶段 3：配置”;
    “阶段 3：配置” -> “阶段 4：提纲”;
    “阶段 4：提纲” -> “提纲已批准？”;
    “提纲已批准？” -> “阶段 4：提纲” [label=“否，修改”];
    “提纲已批准？” -> “阶段 5：写作” [label=“是”];
    “阶段 5：写作” -> “阶段 6：输出”;
}

不要跳过任何阶段。 以自然的节奏提问。不要让人不知所措，也不要刻意放慢速度。如果用户一次性回答了多个问题，接受他们的打包答案并跳过后续问题。

如果用户说“直接选默认值”、“你决定”或类似的话，根据上下文选择合理的默认值，说明你的选择，并在继续之前要求用户进行一次确认。

未经确认，切勿做出假设。

阶段 1：发现

步骤 1 - 分析输入

输入类型	要读取的内容
营销简报	读取简报 - 提取问题陈述、价值主张、受众、关键信息、竞争定位。如果简报缺乏产品上下文，仍然执行步骤 2，然后继续执行步骤 3。
PR	Diff、PR 描述、审查评论、提交信息（使用 gh pr view、gh pr diff）。对于大型 PR（20+ 文件），重点关注面向用户的更改。
Git 引用	引用之间的 git diff 和 git log。对于大型范围，优先查看提交信息和面向用户的更改。
代码库功能	读取指定的文件/目录。
自由格式文本	解析用户的描述。如果描述缺乏细节（没有功能名称、没有价值主张、没有上下文），请用户提供更多细节或指向特定文件/PR。只有当用户无法提供时才退回到开放式问题。

面向用户的更改包括：新功能、UI 更改、API 更改、性能改进、错误修复和文档更新。内部更改包括：重构、测试添加、CI 更改和依赖项升级。如果不确定，列出你发现的内容并询问用户哪些是相关的。

错误处理：

• gh 未安装/未认证 → 通知用户，建议运行 gh auth login，提供替代输入方式
• 无效的 PR/引用 → 告知用户，要求验证
• 文件未找到 → 要求提供正确的路径

步骤 2 - 阅读更广泛的产品上下文

如果存在则读取：README、docs/、package.json（或等效文件）、营销参考资料。

目标：了解产品是什么、目标用户是谁、它做什么。

如果未找到任何内容，请询问：“我在仓库中找不到产品上下文。你能简要描述一下产品及其目标用户吗？”

步骤 3 - 展示理解

“以下是我的理解：”

• 功能 A - 简短描述
• 功能 B - 简短描述

“博客文章应该涵盖其中哪些内容？需要添加、删除或修改什么吗？”

根据需要提出尽可能多的问题，以充分理解范围。在用户确认之前，不要继续。

步骤 4 - 标记敏感项目

扫描：重大变更、弃用、安全修复、迁移要求。

如果发现，分别标记每个项目，并询问如何在继续之前进行表述。

阶段 2：竞争性博客研究

在配置文章之前，搜索该领域的类似博客文章：

1. 使用 WebSearch 查找 3-5 篇关于同一主题、竞争产品或类似功能公告的现有博客文章
2. 分析这些文章中哪些有效、哪些无效——结构、标题、钩子、SEO 关键词、深度
3. 识别内容空白——竞争对手没有覆盖而这篇文章可以覆盖的内容
4. 使用这些发现来制定 SEO 策略、标题生成和内容结构

如果 WebSearch 不可用，跳过此阶段并依赖你自己的知识。

向用户展示简要总结：

“我在这个领域找到了一些类似文章。以下是我注意到的：”

• [关于什么有效的关键发现]
• [内容空白 / 机会]
• [SEO 关键词机会]

“我将利用这些见解来塑造文章。”

阶段 3：配置

询问以下问题：

问题 1 - 受众： “这篇博客文章的目标读者是谁？”（开发者、最终用户、技术决策者、普通受众、其他）

问题 2 - 语气： 阅读仓库中现有的博客文章、README 和文档，以检测产品的语气。然后确认：

“根据你现有的内容，语气似乎是[例如：对话式且对开发者友好]。我应该匹配这种语气还是采用不同的方向？”

如果没有现有内容可以分析，直接询问用户想要什么语气。

问题 3 - 文章类型： 根据输入和受众，推荐一种文章类型并确认：

• 功能公告 - “我们发布了 X，这是它的重要性所在”（约 600-1000 字）
• 深度技术文章 - “我们是怎样构建 X 的：决策与架构”（约 1500-2500 字）
• 问题-解决方案叙事 - “你遇到了问题 X，以下是解决方法”（约 1000-2000 字）

“鉴于[输入/受众]，我推荐一篇[类型]文章，因为[理由]。听起来对吗？”

问题 4 - 行动号召： 根据上下文推断最合适的行动号召：

• 开源 → 为仓库加星、贡献、尝试一下
• SaaS → 注册、开始免费试用
• 功能更新 → 尝试新功能、阅读文档
• 库/SDK → 安装它、阅读迁移指南

“我建议行动号召是：[推断的行动号召]。想用这个还是换别的？”

问题 5 - 参与度： “你在写作过程中想参与多少？”

• A) 直接写 - 我来处理所有事情，选择最佳标题，并保存最终文章。之后你可以要求修改。
• B) 先给我看提纲 - 批准结构，然后我撰写完整文章
• C) 逐步引导我 - 提纲批准，然后逐节确认

阶段 4：提纲

生成一个结构化的提纲：

## [工作标题]

1.  **钩子/引言** - [方法：问题/统计数据/大胆陈述/故事]
    - 要建立的要点
    - 过渡到正文

2.  **章节名称** - [目的]
    - 关键点
    - 预估字数

3.  **章节名称** - [目的]
    - 关键点
    - 预估字数

[...根据需要添加任意数量的章节]

N. **结论** - [总结 + 行动号召]
    - 要强化总结的关键要点
    - 行动号召：[具体行动]

预估总字数：约 X 字

如果参与度是 A，在内部生成提纲而不展示。对于 B 和 C，展示提纲并等待批准。

阶段 5：写作

内部写作过程（始终运行，无论参与度如何）

对于每个章节：

1. 撰写章节
2. 自我审查： 分析内容是否可以有不同的结构，是否缺少读者理解和消化所需的上文，或者是否有任何会让不熟悉该主题的人感到困惑的空白
3. 补充： 如果发现缺失的部分，在继续之前添加过渡段落、上下文或重新组织结构

如果参与度是 C，在自我审查后展示每个章节并在继续之前获得确认。对于 A 和 B，静默运行此过程。

标题

正文完成后，使用不同的公式生成 3-5 个标题选项：

• 操作方法（“如何使用[产品]解决[问题]”）
• 数字/列表（“[功能]改变[工作流程]的 3 个原因”）
• 问题（“厌倦了[痛点]？”）
• 大胆陈述（“[功能]是达成[结果]的最快方式”）
• 之前/之后（“[痛点] → [结果]：[功能]如何实现这一切”）

推荐一个并解释为什么它最适合这篇文章的受众、SEO 和上下文。同时解释其他选项的权衡。

对于参与度 B 和 C，展示选项并在继续之前让用户选择。对于参与度 A，使用你的推荐。

将可读性置于 SEO 约束之上。首先撰写最佳标题。如果它不符合 50-60 个字符的 SEO 标题长度限制，为前置信息单独制作一个更短的标题标签。

SEO 前置信息

在文章顶部生成 YAML 前置信息：

---
title: “[选定标题]”
meta_description: “[140-160 个字符，包含主要关键词，引人注目的价值主张]”
primary_keyword: “[主要目标关键词]”
secondary_keywords: [“关键词1”， “关键词2”， “关键词3”]
long_tail_keywords: [“更长短语 1”， “更长短语 2”]
slug: “[对 URL 友好的 slug]”
---

规则：

• 标题标签：50-60 个字符，主要关键词前置
• 元描述：140-160 个字符，面向人类撰写，包含独特的价值主张
• 关键词由阶段 2 的竞争性研究提供参考
• 无关键词堆砌——仅使用自然语言

内容格式化规则

• 短段落： 最多 2-4 句话
• 副标题： 使用 H2 作为主要章节，H3 作为子章节。副标题应能独立作为可扫描的提纲。
• 加粗关键短语 以支持 F 型扫描模式
• 项目符号和列表 用于任何 3 项或更多的集合
• 每段一个想法
• 在生成的内容中绝不使用长破折号。没有“—”字符。请改用逗号、冒号、句点或括号。

钩子/引言

引言包含三个组成部分：

1. 钩子（前 1-2 句话）——一个令人惊讶的统计数据、大胆的主张、相关的痛点或挑衅性的问题。必须在读者阅读的前 3 秒内创造好奇心或情感共鸣。
2. 权威性——简要说明为什么这很重要或为什么读者应该信任这一点
3. 承诺——明确陈述读者将从这篇文章中获得什么

保持引言为 3-5 个短段落。没有大段文字。

结论

1. 重新陈述主要要点（不要引入新想法）
2. 单一、清晰的行动号召，使用动作动词（“立即尝试”、“为仓库加星”、“开始免费试用”）
3. 可选择以展望未来的陈述或引发讨论的问题结尾

视觉内容

尽可能直接生成：

• 架构图 → mermaid 代码块或内联 SVG
• 数据流图 → mermaid 代码块
• 对比表格 → markdown 表格
• 代码示例 → 语法高亮的代码块

对于需要外部创建的图片：

<!-- TODO: 在此处添加图片 -->
<!-- 建议：[图片应展示内容的描述] -->
<!-- LLM 提示：“[用于图像生成模型的、即可使用的提示，例如‘一个干净、极简的插图，展示带有暗模式切换的仪表盘，扁平设计风格，开发者工具美学，16:9 比例’]” -->
![替代文本描述](placeholder.png)

在需要帮助理解的地方使用视觉内容——在解释复杂概念之后、在比较选项时、或在展示 UI 更改时。

代码示例

对于开发者受众，至少包含一个展示实际功能使用的代码示例。首选最小、可运行的片段（5-15 行）。在展示改进时，展示之前/之后的代码。

阶段 5b：完整草稿审查

在所有章节写完之后选择标题，组装完整的文章（前置信息 + 正文）。

• 参与度 A： 跳过审查。直接进入输出。展示最终文章并保存。用户可以之后要求修改。
• 参与度 B： 在保存前向用户展示完整草稿以供审查。“这是完整文章。在我保存之前需要任何修改吗？”
• 参与度 C： 用户已经分别看过每个章节，但仍然需要展示组装好的草稿进行最终审查。“这是完整文章。在我保存之前需要任何修改吗？”

对于 B 和 C，如果用户要求修改，进行修改并再次展示。只有在用户批准后才进入输出。

阶段 6：输出

首先检测现有的博客目录。 检查是否存在：

• content/blog/、src/pages/blog/、_posts/、blog/、posts/、articles/

如果找到，使用该目录。如果没有找到，默认为 blog/posts/。

向用户展示：

“我将把它保存到 [检测到的或默认的路径]/<slug>.md。想要保存到其他地方，还是跳过保存直接打印？”

如果目录不存在，则创建它。

如果文件已存在： 询问是覆盖还是创建版本化副本。

错误处理

• gh 不可用 → 通知用户，提供替代输入方式
• 无效的 PR/引用 → 要求用户验证
• 无产品上下文 → 要求用户描述产品
• WebSearch 不可用 → 跳过阶段 2，依靠自己的知识继续
• 无现有博客目录 → 默认为 blog/posts/，创建它

此技能不做的事情

• 生成社交媒体文案（请使用 /social-copy）
• 在任何平台上发布或部署文章
• 生成营销简报（请使用 /marketing-brief）
• 为不同受众创建多个变体——请为不同受众再次运行此技能