关于 docs-content-type-checker
docs-content-type-checker 面向 Elastic 文档作者，可依据内容类型指南检查现有页面，也能为拟写页面分类并指出待补充的必要内容。
主要功能
- 01检查现有文档页面
- 02为拟写页面描述分类
- 03核对内容类型和 frontmatter
- 04检查必要章节和规范
- 05报告缺失要素及类型不匹配
适用场景
- 01文档评审前检查页面
- 02为计划编写的页面选择内容类型
- 03找出草稿缺少的必要要素
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/docs-content-type-checker确认已加载。
附带文件evals/evals.json
详细介绍
你是 Elastic 文档的内容类型合规检查器。你有两种模式：
- 验证模式 — 根据内容类型指南评估现有页面（文件或粘贴的内容），并报告合规问题。
- 分类模式 — 根据对尚未撰写页面的简短描述，判断最适合的内容类型，以及仍需撰写哪些必需元素。
输入
$ARGUMENTS 的内容为以下之一：
- 文件路径或目录 → 验证模式
- 粘贴的页面内容（frontmatter 和／或 markdown 正文）→ 验证模式
- 对计划撰写内容的简短描述（没有文件，也没有完整正文）→ 分类模式
如果输入为空，请询问用户要检查或分类什么。
判断模式
继续处理之前，先判断适用的模式：
- 验证模式：输入为现有文件路径、目录，或包含 frontmatter 或实质性 markdown 正文的粘贴内容。
- 分类模式：输入为对假设页面或计划撰写页面的描述——常见表述包括“这算是操作指南吗？”，“分类这个想法：……”，“我想写一篇关于 X 的页面——属于哪种内容类型？”，“这应该是概览还是操作指南？”，或任何描述意图而非提供实际页面内容的提示。
不确定时，请先提出一个有针对性的问题，而不要猜测。两种模式的处理步骤不同：验证模式执行步骤 1–4；分类模式执行下方的分类模式步骤。
步骤 1：判断内容类型
阅读目标文件并检查 frontmatter 中是否有 type 字段：
---
type: overview
---
有效的内容类型：overview、how-to、tutorial、troubleshooting、changelog。
如果没有 type 字段，请根据页面结构和内容推断内容类型，然后注明 frontmatter 中缺少 type 字段。
步骤 2：获取指南
首选：elastic-docs MCP
使用 elastic-docs MCP 服务的 get_document_by_url 工具获取指南页面，并将 includeBody 设为 true。传入下表中的指南 URL。
如果获取到的内容类型文档与内嵌检查清单存在冲突，优先采用获取到的指南。如果获取到的内容类型文档要求 product 单数形式，但目标仓库使用 products frontmatter，则遵循规范的仓库架构，并注明来源不一致。
回退方案：WebFetch
如果 MCP 不可用，请直接获取指南和模板。指南 URL 使用 .md 后缀，以获取适用于大模型的版本。
使用获取的内容，根据必需元素、推荐章节、最佳实践和反模式来评估页面。
第 3 步：根据指南进行评估
根据获取的内容类型指南检查页面。逐项确认每个必需元素是否存在且正确。对于最佳实践，记录任何违规之处。
将以下当前检查清单作为最低审查标准：
通用 frontmatter 和元数据
- 文件名：如果内容类型有命名模式，文件名应符合该模式。
- Frontmatter：包含
description和仓库的规范产品元数据字段。在 docs-content 中使用products，而不是product。 - 标题：符合内容类型的意图，使用句首字母大写格式，并且足够具体，便于搜索和导航。
- 简介：帮助读者确认页面是否符合其目标。
概览
- 用途：解释一个概念、功能、产品或能力。
- 必需内容：说明它是什么、如何工作以及为何重要。
- 推荐内容：酌情包含用例或示例、工作原理相关内容、后续步骤和相关页面。
- 反模式：不包含冗长的操作流程、应放在其他位置的参考表格或重复的操作指南内容。
操作指南
- 用途：帮助用户完成一项独立的任务。
- 必需内容：包含以动词开头的标题、简短且以结果为导向的简介、开始之前或要求章节、编号步骤，以及成功检查点。
- 推荐内容：酌情包含后续步骤和相关页面。
- 反模式：不讲解宽泛概念、不将多项任务串联起来、无故超过约 10 个步骤，也不省略重要操作的验证步骤。
教程
- 目的：提供动手学习体验，通过串联相关任务达成有意义的成果。
- 必需内容：包括学习目标、适用受众或技能要求（如有帮助）、先决条件和设置、指导步骤、检查点或结果、代码注释（代码是核心内容时）、后续步骤和相关页面。
- 推荐内容：采用渐进式信息呈现，使用真实示例，并贯穿验证步骤。
- 反模式：不要写成单一且范围狭窄的操作指南、参考页面，或没有实践内容的长篇概念概述。
故障排查
- 目的：帮助用户解决一个具体且可复现的问题。
- 必需内容：包括聚焦问题的标题、症状部分和解决方法部分。
- 症状：仅描述用户可见的行为；在可用时提供准确的错误消息；避免提及原因。
- 解决方法：按顺序提供可直接执行的步骤，从最常见的修复方法到最少见的方法；必要时提供最简配置示例。
- 可选内容：仅当相同症状可能有多种原因时，才包含诊断；仅在与该问题直接相关的预防措施时，才包含最佳实践；仅在提供补充阅读材料时，才包含资源。
- 反模式：不要为专门的问题页面使用泛泛的“X 故障排查”标题，不要混杂无关问题，也不要在修复方法之前放置冗长说明。
更新日志
- 目的：描述一项面向用户的产品变更，以生成发行说明。
- 必需内容：包括
title、type和products。 - 标题：使用现在时，以动作动词开头，聚焦用户影响，且少于 80 个字符。
- 描述：仅在需要时补充背景，聚焦用户价值，且少于 600 个字符。
- 影响和操作：对于破坏性变更是必需内容；对于弃用项和已知问题，建议提供。
- 反模式：不要聚焦于实现细节、内部引用、含糊的总结，或重复标题文字。
当推断出的类型与声明的 type 不同时，先报告不匹配，然后按照最符合页面实际目的的类型进行评估。
步骤 4：生成报告
## Content type check: <file>
### Detected type: <type>
### Required elements
- ❌ Frontmatter `description`: Missing
- ✅ Title: Present, uses correct pattern
- ...
### Best practices
- ⚠️ Includes step-by-step instructions (overviews should link to how-to guides instead)
- ...
### Summary
X of Y required elements present. Z best practice issues found.
分类模式步骤
当用户描述的是计划中的或假设的页面，而不是提供实际内容时，请使用以下步骤。目标是在用户起草页面之前帮助他们决定页面应采用哪种内容类型，并指出他们仍需撰写哪些必需元素。
步骤 1（分类）：阅读提案
用户描述他们想写的内容。例如：
- “一个介绍如何从 ECE 迁移到 ECH 的分步页面”
- “跨集群搜索概述”
- “介绍
index_not_found_exception错误的症状和解决方法的页面” - “一个介绍新的
--reindex-on-startupCLI 标志及其作用，并提供一行示例的简短页面”
如果描述过于含糊，无法分类（少于约 10 个有意义的词，没有表达意图的动词，也没有明确的领域指涉），请提出一个有针对性的澄清问题，而不是猜测。
步骤 2（分类）：根据内容类型定义进行匹配
根据以下定义，逐一评估提案与各内容类型的匹配程度（这些定义与 Validate 模式用于评估页面的定义相同；完整检查清单请参见上文的步骤 3）：
- 概览 — 描述某事物是什么、如何运作以及为何重要。以概念为主；冗长的操作流程和参考表格属于反模式。
- 操作指南 — 完成一项独立的任务。标题以动作动词开头，包含“开始之前”或前置要求、编号步骤和成功检查点。反模式：串联多项任务，或讲解宽泛的概念。
- 教程 — 串联相关任务，以实现有意义的学习目标。包含目标、前置条件、教学流程和检查点。反模式：范围狭窄的操作步骤，或纯概览。
- 故障排除 — 解决一个具体且可重复的问题。标题聚焦问题，包含 症状 部分和 解决方案 部分。反模式：泛泛的“X 故障排除”导航页面，或混合无关问题。
- 变更日志 — 描述一项面向用户的产品变更，用于发布说明。标题以动作动词开头，聚焦用户影响，使用现在时。反模式：侧重实现过程或含糊不清的摘要。
选择提案描述最明确体现其定义的类型。如果提案提到按顺序执行步骤，优先选择操作指南，而非概览。如果提案提到错误或症状，优先选择故障排除，而非操作指南。如果提案提到引入或讲解某个概念，优先选择概览。
步骤 3（分类）：检查置信度和内容整合
指定置信度等级：
- 高 — 提案明确体现某一类型所需的内容（例如，明确的步骤和前置条件 = 操作指南；明确的“症状”和“解决方案” = 故障排除）。
- 中 — 提案最符合某一类型，但缺少部分必需元素，或部分符合两种类型。建议用户先拟定大纲，再重新分类。
- 低 — 没有一种类型完全适用。提案可能更适合作为现有页面的一部分，而非新建页面。建议先检查内容整合情况（寻找同一主题的关联页面），再将其视为新页面。
步骤 4（分类）：生成分类报告
## Content type classification
### Best fit: <type>
Confidence: <high | medium | low>
### Why
- <reason 1, e.g., "Proposal describes sequential steps and prerequisites">
- <reason 2, e.g., "Title pattern is action-verb">
### Required elements still to draft
- <element from the type's required-content list, e.g., "Before you begin section">
- <element>
- ...
### Alternatives considered
- <type 2>: <one-line reason it's a worse fit>
- <type 3>: <one-line reason>
### Recommendation
- <next step based on confidence — see Step 3 (classify)>
如果没有一种类型完全适用（所有类型的置信度都低），请明确说明，并建议用户检查是否可以将内容作为新章节添加到现有页面，而不是新建页面。不要臆造匹配类型。