MD-CREATE-SKILL

---
name: markdown-create
description: MUST be invoked BEFORE writing or editing any .md file.
---

# Markdown 撰写指南

## 核心理念

Markdown 是**为读者服务**的轻量结构。本 skill 的所有规则都从这一点出发:

- **让结构帮读者快速找到信息**,不为炫技
- 用最少的语法,**散文优先**——一句话能说清就别用列表
- 不同类型文档有不同约定,**先识别类型,再套规则**
- 不用 Emoji 或其他非标准符号做装饰,**markdown 语法本身就够**

## 第一步:识别文档类型

拿到撰写请求,先判断属于哪一类——三类规则不同。

| 类型 | 典型场景 | 风格基调 |
|---|---|---|
| **发布文档** | README、博客、技术文档、对外公开的指南 | 正式、有完整结构、给陌生读者 |
| **记忆文档** | 学习笔记、个人总结、调研报告 | 自由、为自己/团队、省客套 |
| **AI/项目文档** | CLAUDE.md、AGENTS.md、系统提示词、CHANGELOG | 紧凑、指令式、面向工具或机器 |

按类型应用的差异点:

- **发布文档**:H1 标题 + 引言段 + 完整章节;主用散文 + 关键处列表;对比用表格
- **记忆文档**:省 H1 或用简短标题;允许大量列表/表格;省引言段
- **AI/项目文档**:祈使句、二阶标题分块、bullet 密集;砍掉"我们应该"这类废话

无法判断时,**默认按发布文档处理**——正式比随便保险。

### 三类文档的语气对比

同一条信息,三类文档的写法差异:

```text
Bad: AI 文档里写发布文档腔:
   "我们建议您在运行测试之前先激活虚拟环境,这样可以确保依赖隔离..."

Good: AI 文档应这样写:
   "运行测试前先激活 venv:`. .venv/bin/activate`"

Bad: 发布文档里写 AI 文档腔:
   "装依赖。跑测试。完成。"

Good: 发布文档应这样写:
   "安装依赖后,运行 `pytest` 即可执行全部测试套件。"
```

## 通用语法规则

### 目录(TOC)

适用场景:**发布文档且篇幅较长**(H2 章节 ≥ 5 个 或 全文 > 800 字)。

- 放在 H1 标题与引言段之后、第一个 H2 之前
- 只列到 H2,最多到 H3——再深读者会迷失
- 优先让渲染器自动生成(GitHub / GitLab / 多数静态站点基于标题生成侧边目录,或支持 `[[TOC]]` 占位符);手写目录容易与标题不同步
- 手写用无序列表 + 锚点:`- [章节名](#章节名)`,锚点遵循渲染器规则(GitHub:小写、空格转 `-`、去标点)

不要:
- 给记忆文档 / AI 文档加 TOC(这两类讲究紧凑,目录是噪声)
- 给短文加 TOC(H2 < 5 时,滚动比目录快)
- 同时维护手写 TOC 和自动 TOC(必然不同步)

### 标题层级

- H1(`#`)全文**只有一个**,且只用于文档标题
- 从 H2(`##`)开始分章节
- 最多用到 H4——超过四层就把结构扁平化
- 标题前后保留空行
- 不在标题里用粗体或代码块(标题本身就是强调)

### 段落与散文

- 短答案、过渡说明、解释性内容——**用散文**,别拆成 bullet
- 段落之间空一行
- 一段聚焦一个观点。**经验阈值**:中文超过 5 句或 200 字就拆段

### 列表(bullet / numbered)

适用场景:**并列项、无固有顺序、3 项或更多**。

- 2 项以下写成散文(例:"A 和 B 两件事",不是两个 bullet)
- 有时间或步骤顺序——用有序列表 `1. 2. 3.`
- 完全可互换、无顺序——用无序列表 `-`
- 项目符号统一用 `-`(别混用 `-` `*` `+`)
- 列表项内多行,缩进 2 个空格续行

嵌套列表**最多 3 层**。再深说明信息结构需要重新组织。

### 加粗(`**...**`)

用于:
- 重要术语首次出现(类似教科书的术语标记)
- 段落中真正的关键结论(一段最多 1-2 处)
- 列表项导读词("注意:..." "警告:...")

不要:
- 整句加粗(几乎不需要)
- 每个 bullet 都加粗(变成噪声)
- 标题里加粗(标题本身就是强调)

### 斜体(`*...*`)

- 英文:用于书名、产品名、外语词、轻度强调
- **中文环境下渲染普遍不佳**(多数中文字体没有真斜体,会显示为伪斜或不变),改用:
  - 书名 / 作品名 → 书名号《...》
  - 强调 → 加粗或引号
  - 外语词 → 原文 + 引号

### 行内代码(`` ` ``)

用于:
- 代码标识符(变量名、函数名、文件路径、命令)
- API 端点、配置键
- 任何需要"原样保留"的短字符串

不要:
- 当"轻度强调"用(那是斜体或加粗的活)
- 套在普通名词上

### 代码块(fenced code)

```python
# 重要的代码加注释解释
def calculate(x):
    return x * 2
```

铁律:

- **必须指定语言**:` ```python ` 而不是 ` ``` `。渲染器要靠它高亮,无障碍也要求。
- shell 用 ` ```bash ` 或 ` ```sh `;输出用 ` ```text `
- 没有合适语言标签时用 ` ```text `
- 示例代码**最精简**——删掉跟示范点无关的 import、错误处理、日志
- 关键代码加**简短**注释解释"为什么",不解释"做什么"(代码自己说)
- 短片段(1-2 个 token)用行内代码 `` `like_this` ``;别为 1 行代码用 fenced 代码块

### 链接

- 优先用行内式 `[文本](url)`;同一 url 重复多次再用引用式 `[文本][id]`
- 链接文字**自带语义**——"[点击这里](url)" 是反模式,改写"[Anthropic 官方文档](url)"
- 只在需要展示完整 URL 时用裸 URL `<https://...>`

### 表格

适用场景:**对比** 或 **结构化属性列表**(行是项目、列是属性)。

```markdown
| 维度 | A 方案 | B 方案 |
|---|---|---|
| 性能 | 高 | 中 |
| 成本 | 高 | 低 |
```

规则:
- 表头分隔行简写成 `|---|---|`,不必对齐字符数
- 单元格内换行用 `<br>`(大多数渲染器支持)
- 单元格内有竖线就转义 `\|`
- **别把长文塞进单元格**——单元格超过 80 字符的内容拆出去做正文

不适合做表格:
- 一两个属性的对象列表(bullet 更轻量)
- 每行差异大、每格几句话的"伪表格"(改用小标题 + 段落)
- 例外:差异大但每格只是几个词的对比(如本指南开头的文档类型对比),仍用表格

### 引用块(`>`)

用于:
- 引用他人原话、文档原文
- 提示框("> 注意:..." "> 提示:...")

**别滥用**做装饰——引用块在长文里割裂阅读流。

### 图表(mermaid / 流程图)

表达流程、架构、时序、关系时,用 mermaid 嵌在代码块里:

````markdown
```mermaid
flowchart LR
  用户 --> CDN
  CDN --> 应用服务器
  应用服务器 --> 数据库
```
````

- mermaid 类型:`flowchart`(流程/架构)、`sequenceDiagram`(时序)、`classDiagram`(类图)、`erDiagram`(ER 图)、`gantt`(甘特图)、`stateDiagram`(状态机)、 `architectureDiagram`(系统架构图)、 `pie`(饼图)、`userJourney`(用户旅程图)
- **下游警告**:文档之后要转 Word 时,mermaid 在某些容器环境无法预渲染,会变成代码块文字。源文件仍写 mermaid——转换时再处理。

## 高频模板(内联)

下面四个模板覆盖 80% 的写作场景。复制骨架,填内容。

### CHANGELOG(Keep a Changelog 约定)

```markdown
# Changelog

本项目所有重要变更记录在此。

格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),版本号采用 [Semantic Versioning](https://semver.org/lang/zh-CN/)。

## [Unreleased]

### Added
- 尚未发布的新增功能

## [1.2.0] - 2026-05-21

### Added
- 新增功能描述(关联 commit / PR)

### Changed
- 已有功能的非破坏性变更

### Deprecated
- 即将移除的功能

### Removed
- 本版本删除的功能

### Fixed
- 缺陷修复

### Security
- 安全相关修复
```

规则要点:

- 分类固定六项:**Added / Changed / Deprecated / Removed / Fixed / Security**,空类别直接省略
- 版本号**倒序排列**,最新在上,`[Unreleased]` 永远置顶
- 日期格式 `YYYY-MM-DD`
- 每条变更**以动词开头**,附带 commit hash / PR 编号

### README

````markdown
# 项目名称

一句话说清这个项目做什么(给完全没听过的读者)。

## 功能特性

- 关键能力 1
- 关键能力 2
- 关键能力 3

## 安装

```bash
npm install xxx
```

## 快速上手

最小可运行示例(5-10 行),让读者 1 分钟内看到效果。

```js
const xxx = require('xxx');
xxx.do();
```

## 使用文档

详细 API / 配置说明,或链接到 `docs/`。

## 贡献

如何提 issue、提 PR、本地跑测试。

## 许可证

MIT / Apache-2.0 / ...
````

规则要点:

- **第一段必须是一句话定位**——读完这一句读者就知道要不要继续看
- "快速上手"放在"完整文档"之前,降低首次接触门槛
- 安装、运行、测试命令都用代码块,**别混在散文里**
- Badge(CI 状态、版本号、覆盖率)放在标题正下方,不超过 5 个

### CLAUDE.md / AGENTS.md(AI/项目文档)

````markdown
# 项目名 — Claude 工作指南

## 项目概览

一段话:这个仓库是做什么的、核心技术栈、主要协作对象。

## 架构

```text
backend/    Flask 后端
frontend/   Vue 前端
extensions/ Shopify 扩展
```

关键模块的职责一句话写清,**别复述目录树**(`ls` 就能看到)。

## 常用命令

```bash
# 后端测试
pytest

# 前端开发服务器
yarn dev

# 数据库迁移
flask db upgrade
```

## 约定

- pip-tools 管依赖,**不要**手编辑 `requirements/*.txt`
- 长跑 CLI 用 `app_utils.prevent_concurrency(key)` 包裹
- 时区是 `Australia/South`(Adelaide)
````

规则要点:

- **祈使句、不啰嗦**:"运行 X""不要 Y",而不是"我们建议您..."
- 只写**从代码看不出**的信息(隐性约定、跨模块默契、踩过的坑)
- 不复述 `ls` / `git log` / `package.json` 能查到的内容
- 命令块要可直接复制运行,别嵌在散文里

## 撰写流程(To Claude)

1. **识别类型**:发布 / 记忆 / AI 三选一,无法判断默认发布
2. **找模板**:四个高频类型直接套上面的骨架
3. **填充内容**:照通用语法规则写
4. **自检**:
   - H1 唯一吗?
   - 有没有"为加而加"的 bullet(2 项以下、内容可合并)?
   - 有没有"为加而加"的 bold(整段加粗、每个 bullet 都加粗)?
   - 代码块都标了语言吗?
   - 表格里塞了长段吗(单元格 > 80 字符)?
   - 嵌套超过 3 层吗?
   - 中文文档里用了渲染不佳的斜体吗?
   - 长发布文档缺 TOC 吗?或反过来,短文 / AI 文档加了 TOC?

## 在聊天回复中(非文档生成)的应用

用户**没明确要 markdown 文件**时,沿用默认对话行为:能散文就散文,需要结构再加结构。本 skill 只规范**生成 markdown 文件/长文档**的场景,不管普通问答。

## 不应使用本 skill 的情况

- 用户要的是非 markdown 输出(纯文本、Word、PDF、HTML)
- 用户只要简短的对话式回答
- 用户在编辑代码,markdown 只是 commit message 顺带提到
- 用户已给出明确风格指南且跟本 skill 冲突——按用户的来