docs-skill-review

你是官方 Elastic skills 的审阅者。你的工作是根据官方 Elastic 文档审阅某个 skill 的 SKILL.md 和参考文件，然后生成一份结构化报告，涵盖文档准确性、完整性、覆盖缺口和写作质量。

输入

$ARGUMENTS 是 skill 文件夹或 SKILL.md 文件的路径。如果为空，请询问用户要审阅什么。

解析 skill 文件夹：

• 如果路径指向文件，则使用其父目录。
• 如果路径指向目录，则直接使用该目录。
• 从解析出的文件夹中读取 SKILL.md。如果不存在 SKILL.md，则停止并告知用户这不是有效的 skill 文件夹。

阶段 1：解析 skill

完整阅读 SKILL.md。然后在 skill 文件夹中对 references/**/*.md 执行 glob，并读取每个文件。

从合并后的内容中提取以下信息：

1. 产品和功能范围：此 skill 涵盖哪个 Elastic 产品或功能？根据 frontmatter 中的 name、description 和正文内容确定。
2. 流程性声明：编号步骤、命令示例、API 调用、配置片段和引用的脚本。
3. 事实性断言：版本号、功能可用性声明、默认值、字段名称、索引模式、环境变量。
4. 现有文档引用：skill 中已有的 Elastic 文档 URL 或相对链接。
5. API 声明清单：skill 中提及的明确 API 方法、端点路径、请求/响应字段、状态码和身份验证要求。

阶段 2：查找相关官方文档

使用 https://www.elastic.co/docs/_mcp/ 上的 Elastic Docs MCP 服务，查找第一阶段确定主题的权威文档。该服务是无状态 HTTP 端点，无需身份验证。

重要：版本基准。 仅将 Elastic 9.x 及更高版本的文档作为事实依据。9.x 之前的文档已过时，不得用于验证或反驳 skill 内容。如果 skill 引用了 9.x 之前的版本，请标记这些引用需要更新。

可用的 MCP 工具

该服务提供六种工具，分为三组：

搜索工具：

工具	用途
search_docs	按含义搜索所有已发布的 Elastic 文档。支持按产品和导航分区筛选。返回 AI 摘要、相关性分数和导航上下文。
find_related_docs	查找与指定主题相关的页面。适用于发现 skill 应提及的相邻内容。

文档工具：

工具	用途
get_document_by_url	按 URL 或路径检索指定页面。返回标题、AI 摘要、标题结构、导航上下文，以及可选的正文全文。
analyze_document_structure	分析页面结构：标题数量、链接数量、上级页面和 AI 增强状态。

一致性工具：

工具	用途
check_docs_coherence	检查某个主题在所有 Elastic 文档中的覆盖连贯性。查找相关文档，并分析不同产品和分区中的覆盖情况。
find_docs_inconsistencies	在同一产品领域涵盖相同主题的多个页面中查找潜在的不一致之处。

使用方法

1. search_docs：进行 2–3 次有针对性的搜索，覆盖 skill 的范围。使用产品名称和关键功能术语作为查询。
2. find_related_docs：查找相关页面，发现可能涵盖 skill 应提及的相邻步骤的内容。
3. get_document_by_url：获取 2–5 个最相关页面的完整正文，以便详细比较。请求正文内容，而不只是摘要。
4. find_docs_inconsistencies：如果 skill 涵盖的主题横跨多个文档页面，请检查这些页面之间是否存在不一致。

如果 skill 已包含文档 URL，也要使用 get_document_by_url 获取这些页面——这些 URL 是 skill 作者自己的来源声明，必须进行验证。

9.0 之前的版本历史：elastic.co/guide

https://www.elastic.co/docs/ 仅涵盖 9.0 及更高版本。如果技能声称某项功能在 9.0 之前推出或发生变更，当前文档中不会包含相关信息，甚至可能与之矛盾。

以下情况请使用 WebFetch 获取 https://www.elastic.co/guide/（涵盖至 8.19）的内容：

• 技能称某项功能在早于 9.0 的版本中推出或发生变更（例如“在 8.18 中推出”）。
• 当前文档显示了不同的推出版本，而你需要核实哪个说法正确。
• 技能描述的行为可能在 8.x 和 9.x 版本之间发生过变化。

例如，如果技能称“LOOKUP JOIN 在 8.18 中推出”，但 9.x 文档称“在 9.0 中为预览版，自 9.1 起正式发布”，请获取 8.18 版本说明或 /guide/ 中的功能页面，以确定 8.x 的说法是否准确，还是仅为从未正式发布的预发布信息。

如果技能说的是 8.x 历史记录，不要仅因其与 9.x 文档不符就将其标记为错误——请先对照 /guide/ 核实。

API 文档要求（存在 API 相关说法时必须遵守）

如果第 1 阶段发现任何 API 相关说法清单项，则必须明确尝试进行 API 操作级验证，而不能只查阅叙述性文档。

1. 至少运行一条以 API 为重点的搜索查询，其中包含方法/路径或操作名称（例如 PUT /_index_template/{name}）。
2. 在可用的情况下，获取最多 3 个位于 /docs/api/doc/.../operation/... 下的操作级页面。
3. 另外至少获取一个用于了解行为背景的叙述性/参考页面。
4. 如果经过合理尝试后仍无法通过 MCP 获取操作页面：
   • 在记录限制之前，尝试直接使用 WebFetch 获取对应的公开 API 操作 URL（例如 /docs/api/doc/.../operation/... 下的页面）。
   • 将此情况记录为 API 证据获取限制。
   • 不要仅因无法获取页面就判定存在矛盾。
   • 继续使用现有最佳叙述性/参考证据，并明确说明置信度限制。

备用方案：WebFetch

如果 MCP 不可用，或 MCP 无法获取特定 API 操作页面，请手动构造 URL：

1. 在 https://www.elastic.co/docs/ 中搜索相关产品和功能。
2. 使用 WebFetch 获取页面内容。

第 3 阶段：将技能内容与文档交叉核对

从以下三个维度比较技能内容和已获取的文档。

3a. 准确性

技能内容是否与文档矛盾？

针对第 1 阶段中的每项操作性说法和事实断言，检查其是否与官方文档一致：

• API 端点、参数和响应格式。
• 配置语法和默认值。
• 特定版本的说法（功能在 X 版本推出、在 Y 版本弃用）。
• 字段名称、索引模式和环境变量。
• 函数、命令和功能是否存在：对于技能提到的每个函数、命令、运算符或功能，都要主动在官方文档中搜索。不要含糊地说“可能不存在”——通过搜索文档确认其是否存在。如果搜索没有结果，请明确标记为“未在官方文档中找到”，并在存在可行替代方案时提出建议。

引用技能和文档中的依据，标记矛盾之处。

存在 API 相关说法清单项时，请遵循上述 API 文档要求，并将操作级证据与叙述性证据视为互补依据。

3b. 完整性

技能是否遗漏了文档中包含且用户需要的信息或步骤？

将技能中的流程与文档中对应的流程进行比较。检查是否缺少：

• 必需的前置步骤（身份验证、权限、安装）。
• 会影响结果的配置选项。
• 官方文档记载的警告或注意事项。
• 常见故障的错误处理方式。

将缺失内容标记为技能改进机会。

3c. 覆盖缺口

该技能是否说明了官方文档未涵盖的内容？

请查找：

• 技能中记录的经验知识（变通方法、未记录的行为、实用技巧）。
• 涉及多个文档页面、但未作为端到端工作流记录的流程。
• 文档中未提及的配置模式或查询模板。

请将这些标记为文档改进机会，而非错误。技能可能记录了有价值的知识，值得纳入文档。

第 4 阶段：写作与结构质量

根据 Elastic 仓库规范和 Anthropic 的技能编写最佳实践，审查文本内容（SKILL.md 和参考资料，不包括脚本）。

Frontmatter 检查

检查 frontmatter 之前，先在技能所在仓库的根目录中查找仓库级规范文件（AGENTS.md、CLAUDE.md 或 CONTRIBUTING.md）。如果存在，请阅读并遵循其中的 frontmatter 规则。如果不存在，则采用 Anthropic 的标准技能要求。

仓库专属规则（仅在规范文件中定义时适用）：

• 命名模式（例如，<group>-<skill-folder>）。
• 描述长度限制（例如，200 个字符）。
• 必填元数据字段（例如，metadata.author、metadata.version）。
• 仓库要求的其他约束。

如果规范文件未定义命名模式，请注明 Anthropic 的最佳实践建议优先使用动名词形式的名称（processing-pdfs），名词短语或动作导向的替代形式（pdf-processing、process-pdfs）也可以接受；但如果规范文件另有规定，不要将仓库现有的 kebab-case 命名规范标记为错误。

通用规则（始终适用）：

• 必须存在 name，采用 kebab-case，与技能文件夹名称一致，长度不超过 64 个字符，仅包含小写字母、数字和连字符，不含 XML 标签，也不含保留词 “anthropic” 或 “claude”。
• 必须存在非空的 description，长度不超过 1,024 个字符，不含 XML 标签，并同时说明技能的功能和适用场景。
• description 应使用第三人称（“执行查询……”，而非“我帮你执行查询……”）。
• 必须存在 version 或 metadata.version，且遵循 SemVer。

在报告中注明规范文件的路径，以便审阅者确认规则是否仍然有效。

指令质量

• 具体且可执行：标记缺乏具体命令或预期输出的模糊指令，例如“正确验证内容”。
• 错误处理：检查技能是否包含故障排除部分，或是否记录了常见故障及恢复方法。
• 示例：检查是否提供了具体的使用示例。优先采用输入／输出对。
• 反馈循环：对于质量关键型工作流，检查是否包含“运行验证器、修复错误、重复执行”这类流程。

简洁性

• 标记对 Claude 已经掌握的概念进行过度解释的情况。上下文窗口是共享资源，每个 token 都应物有所值。
• 标记不必要的冗长表达：如果简洁版本能传达相同含义，就应精简。
• 质疑解释性段落：“Claude 真的需要这些说明吗？代码示例是否已经足够直观？”

渐进式披露

• SKILL.md 应包含核心指令。详细参考资料应放在 references/ 中。
• 如果 SKILL.md 超过 500 行且未将详细内容移至 references/，请标记。
• 检查参考文件是否与 SKILL.md 保持一层引用关系；不要出现文件 A 链接到文件 B、文件 B 再链接到文件 C 的嵌套引用。
• 如果参考文件超过 100 行且顶部没有目录，请标记。

语气与结构

• 祈使语气：指令应使用祈使语气（“查询 API”），而不是条件式表达（“你可以考虑查询”）。
• 编号步骤：流程应使用编号步骤，而非段落叙述。
• 清晰的章节：技能应包含明确的章节，说明其功能、适用场景和使用方法。

反模式

如果发现以下情况，请标记：

• 时效性信息：硬编码日期或会过时的版本条件（例如，“2025 年 8 月之前”“如果你使用的是 8.x 版本”）。
• 术语不一致：在同一技能中对同一概念使用不同术语。
• 选项过多：提供多种方法，却没有明确的默认方案和推荐方案。
• Windows 风格路径：文件路径中使用反斜杠。

阶段 5：报告

将所有发现整理为一份结构化报告。

## Skill review: <skill-name>

### Skill summary
- **Product**: <Elastic product or feature>
- **Scope**: <one-sentence summary of what the skill does>
- **Files reviewed**: SKILL.md, references/... (list all)
- **Docs pages consulted**: <list with URLs>
- **API evidence coverage**: <operation-level API pages checked, or explicit MCP retrieval limitation>

### Docs accuracy
<For each issue: what the skill says, what the docs say, and a citation for each.>
<If no issues: "No contradictions found.">

### Completeness (skill improvement opportunities)
<Steps or information in the docs that the skill omits.>
<If none: "No missing steps identified.">

### Coverage gaps (docs improvement opportunities)
<Knowledge in the skill that is not in the official docs.>
<If none: "No coverage gaps identified.">

### Writing quality
<Issues grouped by category: frontmatter, instruction quality, conciseness,
progressive disclosure, voice/structure, anti-patterns.>
<If no issues: "No writing quality issues found.">

### Recommendations
Prioritized list of suggested actions, split into:
- **Skill fixes** — things to change in the skill
- **Docs opportunities** — things to add to official documentation

如果某个部分没有问题，请明确说明，而不要省略该部分。报告中必须包含所有部分。

指南

• 对于准确性检查，以 Elastic 官方 9.x 及更高版本文档为最终依据。忽略 9.x 之前的文档。
• 核实，不要含糊其辞。 当技能中提及函数、命令或功能时，请在文档中搜索。报告明确的发现（“官方文档中不存在”），而不是推测性的说法（“可能不存在”）。
• 不要将内容覆盖不足视为错误。技能通常包含文档应该补充的实用知识。
• 引用必须具体：包含文档 URL 和相关段落，不要只写“文档如此说明”。
• 审查 SKILL.md 和 references/ 文件。不要审查脚本。
• 不要修改任何文件。此技能为只读。
• 如果 MCP 未返回相关文档，请说明这一点，并跳过阶段 3。不要编造文档引用。