documentation-standards

文档规范

自我演进的技能：此技能会随着使用不断改进。如果说明有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

概述

编写 Markdown 文档的规范，旨在同时优化大模型阅读体验，并支持使用 Pandoc 转换为专业 PDF。确保所有文档风格一致。

何时使用此技能

适用于以下场景：

• 编写 Markdown 文档（README、技能、指南、规范）
• 创建包含 Markdown 内容的新技能
• 编写可能会转换为 PDF 的内容
• 检查文档是否符合规范

核心原则

1. 面向大模型优化的文档架构

机器可读格式优先：OpenAPI 3.1.0 规范、JSON Schema、YAML 规范优先于面向人的文档。

原因：结构化格式能提供明确无歧义的约定，方便人类和大模型可靠地读取。面向人的文档用于补充机器可读规范，而非取代它们。

应用方式：

• 工作流规范 → specifications/ 中的 OpenAPI 3.1.1 YAML
• 数据 Schema → 带有示例的 JSON Schema
• 配置 → 带有验证 Schema 的 YAML
• 面向人的文档 → 引用规范的机器可读规格的 Markdown 文档

2. 中心辐射式渐进披露

模式：中心文档（如 CLAUDE.md、INDEX.md）链接到详细的辐射文档（技能、文档目录）。

结构：

CLAUDE.md (Hub - Essentials Only)
    ↓ links to
Skills (Spokes - Progressive Disclosure)
    ├── SKILL.md (Overview + Quick Start)
    └── references/ (Detailed Documentation)

规则：

• 中心文档仅包含要点（是什么 + 去哪里查找更多信息）
• 辐射文档包含渐进展开的详细信息（按需加载）
• 每个主题只有一个真实信息源（不重复）

3. Markdown 章节编号

重要规则：切勿手动为 Markdown 标题编号。

❌ 错误：

## 1. Introduction

### 1.1 Background

### 1.2 Objectives

## 2. Implementation

✅ 正确：

## Introduction

### Background

### Objectives

## Implementation

理由：

• Pandoc 的 --number-sections 标志会在生成 PDF 时自动为所有章节编号
• 手动编号会造成重复：渲染后的输出中会出现“1. 1. 引言”
• 自动编号保持一致，并会在章节重组时自动更新
• 适用于所有 Markdown：文档、技能、项目文件、README 文件

规则：如果 Markdown 文档将来可能转换为 PDF，切勿手动为标题编号。使用语义化标题层级（##、###），并交由工具处理编号。

标准检查清单

创建或审查文档时，请使用此清单：

结构

• 遵循中心辐射式模式（主文档包含要点，参考资料包含详细信息）
• 链接到更深入的文档，以便渐进披露
• 只有一个真实信息源（不同文档之间没有重复内容）

Markdown 格式

• 标题中没有手动添加章节编号
• 正确使用语义化标题层级（##、###、####）
• 代码块包含用于语法高亮的语言标识符
• 链接使用 Markdown 格式 [text](url)，而非裸 URL

机器可读内容

• 工作流使用 OpenAPI 3.1.1 规范进行文档化（适用时）
• 数据结构使用 JSON Schema（适用时）
• 配置使用带验证规则的 YAML（适用时）
• 面向人的文档引用规范的机器可读规格

文件组织

• 文档位于合适的位置：
  • 全局规范 → docs/standards/
  • 技能文档 → skills/{skill-name}/references/
  • 项目文档 → {project}/.claude/ 或 {project}/docs/
• 索引文件提供导航（INDEX.md、README.md）

相关资源

• ASCII 图验证：ascii-diagram-validator - 验证 Markdown 中的 ASCII 图
• 技能架构：请参阅 skill-architecture 插件，了解如何创建有效的技能

示例

良好的中心辐射式结构

中心文档（CLAUDE.md）：

## PDF Generation from Markdown

**Quick Start**: Use pandoc-pdf-generation skill

**Critical Rules**:

1. Never write ad-hoc pandoc commands
2. Always verify PDFs before presenting
3. See skill for detailed principles

辐射文档（skill/SKILL.md）：

• 提供带示例的快速入门
• 链接到 references/，以查看详细文档
• 按需渐进披露

优质机器可读文档

工作流规范（specifications/hook-prompt-capture.yaml）：

openapi: 3.1.1
info:
  title: Hook Prompt Capture Workflow
  version: 1.0.0
paths:
  /capture-prompt:
    post:
      summary: Capture user prompt from hook
      # ... detailed spec

面向人的文档（README.md）：

## Workflow

See [hook-prompt-capture.yaml](./specifications/hook-prompt-capture.yaml)
for complete workflow specification.

Quick overview: ...

总结

文档标准可确保：

• 所有工作区文档的一致性
• 通过机器可读格式优化大模型处理
• 通过中心辐射式结构 + 单一事实来源提升可维护性
• 通过恰当的 Markdown 格式确保 PDF 兼容性

所有文档都应遵循这些标准。

---

故障排查

问题	原因	解决方案
PDF 中章节编号重复	Markdown 中手动编号	删除手动编号，仅使用 --number-sections
PDF 中的链接失效	相对路径不正确	跨文档链接使用仓库根目录路径
代码块没有语法高亮	缺少语言标识符	在开头的三个反引号后添加语言标识符
表格渲染效果不佳	列宽过宽	使用更短的表头或管道表格格式
中心文档过长	中心文档中的细节过多	将细节移至辐射文档，并从中心文档添加链接
内容重复	多个文档中包含相同信息	确定单一事实来源，删除重复内容并添加链接
YAML 规范无法渲染	文件扩展名错误	OpenAPI 规范使用 .yaml 扩展名
缺少索引导航	没有 INDEX.md 或 README.md	在每个目录中创建导航索引

执行后反思

此技能完成后，在结束前检查：

1. 命令是否成功？ — 如果没有，修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口有变化，更新用法示例和参数表以保持一致。
3. 是否需要变通处理？ — 如果你需要临时调整（使用不同的标志、增加额外步骤），请更新此 SKILL.md，以便下次调用时无需重复采用相同的变通方法。

仅当问题真实存在且可复现时才进行更新，不要基于猜测更新。