本指南规范了本书模板中六类内容模块的统一展示格式。与 callout-style-guide.md 配合使用。
根据概念的正式程度分两级处理：
日常概念（首次出现但不需要专门定义的）：在正文段落中自然引出，用一两句话说清楚是什么、做什么。
专业术语或核心机制（需要读者记住的正式定义）：使用 callout-note 并带"定义"或"词条"字段：
::: {.callout-note}
## 词条：渐进式披露
**定义**：系统根据匹配程度分层展示 Skill 内容的机制。
**作用**：减少上下文占用，只在需要时加载完整指令。
:::判断标准：如果一个概念在后续章节还会反复出现，用 callout-note 给出正式定义；如果只在当前段落用一次，写进正文即可。
- 文件名、目录名、命令名一律用行内代码标记：
`CLAUDE.md`、`.claude/skills/`、`git status` - 不需要额外格式，保持行内即可
- 已在所有章节中 100% 一致，继续保持
使用 txt 代码块 + 树形字符 + 右侧注释：
```txt
project/
├── inputs/ # 原始材料
├── outputs/ # 最终交付物
├── references/ # 模板与背景
└── CLAUDE.md # 项目规则文件
### 字段/组件列表
使用表格，列顺序统一为：**名称 → 说明 → 补充信息**
```markdown
| 字段 | 说明 | 是否必填 |
|:---|:---|:---:|
| `name` | kebab-case 格式的唯一标识 | 必填 |
| `description` | 触发匹配的核心依据 | 必填 |
| `model` | 指定运行模型 | 选填 |
注意：表格列数保持 3-4 列，不要超过 5 列。"说明"列始终紧跟"名称"列。
使用语义化代码块（agent、skill）或对应语言标记（yaml、json）。
根据内容性质选择三种格式之一：
1. 运行 `git status` 查看当前改动
2. 用 `git add` 把需要的文件加入暂存区
3. 用 `git commit -m "..."` 提交编号列表中可嵌入代码块，但每步说明控制在 1-2 句。
```{mermaid}
flowchart LR
A[探索现场] --> B[提交计划] --> C[分步执行] --> D[阶段确认]
```不要把并列要点强行编号。如果各项之间没有先后关系，用无序列表或分段说明。
每节核心概念至少提供 2 个示例：一个最小示例，一个领域场景示例。
使用三级标题标注示例类别：
### 最小示例
一个只包含必填字段的基本配置：
```skill
---
name: meeting-summary
description: 会议纪要生成
---
读取会议记录，输出结构化纪要。---
name: quarterly-earnings-summary
description: 季度财报摘要
---
从 SEC 财报中提取核心指标...
### 反面示例（可选）
当常见错误值得单独展示时，用对比格式：
```markdown
**容易踩的坑**：把所有规则都写进一个 Skill
```skill
# ❌ 不推荐
---
name: do-everything
description: 处理所有任务
---
改进写法：按职责拆分
# ✅ 推荐
---
name: format-check
description: 检查输出格式
---
## 六、注意事项（Callout）
### ABC 序号禁令
节（`##`）下面禁止使用 `### A.`/`### B.`/`### C.` 等字母序号。替代方案：
- 并列要点 → 有意义的 `###` 名称或无序列表
- 简短并列条目（每项 1-3 句） → 无序列表或表格
- 有先后顺序的步骤 → 编号列表
- 案例节 → `### 项目目录`/`### 配置文件`/`### 用户操作`
### 段落长度规范
- 单段不超过 200 个中文字符（含标点，不含代码块和图片引用）
- 禁止连续 3 段以上纯文字无代码块/表格/列表/图片/callout 打断
- 列表项每项不超过 2 行
详见 `callout-style-guide.md`。补充以下密度建议：
| 章节类型 | 每节建议 Callout 数 | 重点类型 |
|:---|:---:|:---|
| foundational chapters | 2-3 | `callout-note`（概念定义）、`callout-warning`（常见错误） |
| mechanism chapters | 2-3 | `callout-tip`（最佳实践）、`callout-important`（核心机制） |
| application chapters | 2-3 | `callout-warning`（误区）、`callout-caution`（故障排除） |
**最低标准**：每节至少 1 个 callout。如果一节超过 800 字且没有任何 callout，需要检查是否遗漏了值得高亮的概念或注意事项。
## 七、节内结构模板
一个典型的内容节按以下顺序组织（不是每项都必须出现）：
配图
引入段落（1-3 句，说明这一节解决什么问题） 概念定义（正文或 callout-note） 结构说明（表格或目录树） 操作步骤（编号列表或 Mermaid） 示例（最小 + 场景化） 注意事项（callout-warning / callout-tip） 小结或过渡（可选，1-2 句）
不要机械套用——如果某节天然以示例驱动（如案例节），可以把示例提前；如果某节只讲一个概念，不需要操作步骤。模板的作用是提供检查清单，不是强制顺序。