markdown-notes-refine

---

name: markdown-notes-refine description: Clean up and modernize technical Markdown notes: fix formatting errors, typos, and overly colloquial phrasing; normalize style and spacing; carefully update clearly outdated tools or libraries while staying faithful to the original content. Use when the user asks to polish, correct, or update existing Markdown notes or documentation. allowed-tools: Read, Write, Grep, Glob

markdown-notes-refine

本 Skill 用于在不改变原意的前提下，系统性地完善技术类 Markdown 笔记，包括用语规范、格式整理，以及在有把握的前提下更新明显过时的技术概念。

当收到与“润色 Markdown 笔记 / 修正 Markdown 文档 / 更新旧笔记”类似的请求时，优先使用本 Skill。

总体原则

1. 以原文为基础

   • 不改变原文的核心信息结构和结论。
   • 优先修复错误、提升表述清晰度，而不是扩写新的内容。

2. 形不改神

   • 可以对句式、语序、标题层级、列表结构做合理调整，以提高可读性。
   • 不随意引入笔记中完全未提到的技术栈、框架或业务设定。

3. 谨慎更新知识

   • 只在非常确定的情况下更新明显过时或错误的概念。
   • 对不确定的内容宁可保留并标记“待确认”，也不要自信给出未经验证的具体结论。

操作步骤

步骤 1：通读和识别范围

1. 通读整篇笔记，理解主题和结构。
2. 识别以下内容区域：
   • 标题与章节结构
   • 段落正文
   • 列表（步骤、要点）
   • 代码块、配置片段、命令行示例
3. 不对代码块中的代码行为做“自动优化”或“重构”，除非与后文的“概念更新”完全一致且非常明确。

步骤 2：修正文案与语气

在不改变含义的前提下，对自然语言做如下处理：

1. 修复错别字、语法错误、标点使用错误。
2. 将过于口语化的表述统一为中性、书面化的技术说明风格，例如：
   • 将“你可以先这样做，然后再……”改为“可以先……，然后……”。
   • 将“我们就直接用 XX 就行了”改为“可以直接使用 XX”。
   • 避免出现大量“你”“我”“我们”等人称，改为客观描述。
3. 删除明显多余的口头语、语气词和冗余重复，例如“其实”“然后呢”“就很简单”“非常非常重要”等。
4. 对模糊或容易误解的句子，在保留原意的前提下适度重写，使其更精确、结构更清晰。

步骤 3：修复 Markdown 格式与排版

1. 标题层级

   • 保证标题使用合法 Markdown 语法：#、##、### 等。
   • 尽量保持层级连续，不从 # 直接跳到 ####。
   • 不随意合并或拆分大章节，除非原结构明显混乱影响阅读。

2. 段落与空行

   • 标题与其下第一段正文之间，最多保留一个空行。
   • 段落与段落之间最多一个空行。
   • 删除重复的空行与尾随空格。
   • 不在同一段落内部插入多余的空行。

3. 列表和强调

   • 统一使用 - 或有序列表 1.，并在标记后保留一个空格。
   • 如果列表项语义上是完整句子，结尾加句号或其他合适标点。
   • 合理使用粗体、斜体、行内代码（code）突出专业术语、命令、配置项。

4. 代码块与行内代码

   • 保留原有代码块语言标记（如 js、bash）。
   • 不对代码块内部逻辑做大幅修改，除非明显是拼写错误（例如命令少了一个字符）且修改后的形式是正确且常见的。
   • 不把自然语言说明误改为代码，避免破坏 Markdown 结构。

步骤 4：修复错误或明显过时的概念

在处理概念、工具、库、框架等内容时遵守以下规则：

1. 明显错误

   • 如果某个技术描述与通用、基础知识明显冲突，并且可以根据广为人知的权威信息确定正确说法，可以直接更正，并尽量保持简洁。
   • 示例：把“HTTP 状态码 200 表示请求失败”更正为“表示请求成功”。

2. 明显过时的工具 / 库 / 框架

   • 当满足以下条件时，可以更新或删减：
     • 官方或社区已经明确弃用该工具 / 库；
     • 存在公认的主流替代方案；
     • 更新不会改变笔记的整体学习目标。
   • 处理方式优先级：
     1. 用新的名称或方案替换，并在附近添加一句简短说明，例如“原文提到的 XXX 已不再维护，这里改为使用 YYY。”
     2. 如果原内容详细说明了已弃用工具的用法且不再具有实践价值，可以适度删减，并补充一句整体性说明。
   • 如仅仅是“可能过时”而不确定，则：
     • 不直接替换为新的方案；
     • 在原内容附近添加提示，例如“该库的维护状态可能已发生变化，建议查阅最新官方文档确认”。

3. 依赖检索时的行为（仅在具备相应工具时）

   • 如可以使用 WebSearch 或其他检索工具访问网络：
     • 优先参考官方文档、标准组织、主流社区文档等高质量来源。
     • 不以单个低可信博客或论坛帖子作为唯一依据。
   • 如果检索结果仍然存在分歧或不确定：
     • 不给出武断结论；
     • 使用中性表述，并明确说明存在不确定性。

示例

以下示例仅用于说明修改风格。

原文片段（示例）：

# HTTP 基础教程

你可以先随便起一个服务器，然后再看看浏览器请求会不会过来。然后我们就知道请求是不是成功了，其实就是这样。

200 状态码一般表示请求失败，大家记一下就行了。

润色后示例：

# HTTP 基础

可以先启动一个简单的 HTTP 服务器，然后在浏览器中发起请求，观察服务器端的日志或响应结果，以确认请求是否按预期到达并被处理。

HTTP 状态码 200 表示请求成功，即服务器已经成功处理了客户端的请求。

实际使用时，请根据用户提供的真实 Markdown 内容进行同类型但不超出范围的修改，不要添加与原文主题无关的额外章节或长篇扩写。