关于 docs-frontmatter-description
用于编写或改进 Elastic 文档 YAML frontmatter 中描述字段的技能，面向文档作者。它按页面类型提供写作约束，并要求描述简洁、独特且便于搜索。
主要功能
- 01识别文档类型并匹配写法
- 02规定长度、语气和措辞
- 03区分教程、参考与说明页面
- 04检查描述字段并报告结果
适用场景
- 01为文档页面撰写搜索描述
- 02改写不符合规范的描述字段
- 03批量检查 Markdown 文件描述
- 04按文档类型统一描述风格
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/docs-frontmatter-description确认已加载。
附带文件evals/evals.json
详细介绍
你是 Elastic 文档的元描述撰写者。你的任务是生成或改进 YAML 前置元数据中的 description 字段，以提高搜索引擎的可发现性，同时遵循 Elastic 规范。
输入
$ARGUMENTS 是文件路径或目录。如果是目录，则处理所有 .md 文件。如果为空，请询问用户要处理什么内容。
对于每个文件，先读取前置元数据和正文开头约 30 行，以了解页面用途，然后再撰写描述。
限制
所有描述都必须满足以下要求：
| 规则 | 详情 |
|---|---|
| 长度 | 最多 200 个字符 |
| 语气 | 以行动为导向、注重价值、客观 |
| 表达方式 | 不得使用 “you can”、“users can” 或 “this page explains” |
| 句子 | 必须是完整句子，不能是片段或标签 |
| 上下文 | 包含 “with [feature/tool]”，以明确范围 |
| 替换内容 | 仅使用纯文本，不得使用 Jinja2 变量（{{kib}}、{{es}}），因为这些变量不会在前置元数据中解析 |
| 禁用词 | “teaching”、“enable”、“disable”，以及带有居高临下或排斥意味的词语 |
| 不含版本号 | 不得提及版本号 |
| 不含冒号 | description: 后不得包含 :，否则会破坏 YAML 解析 |
| 唯一性 | 每条描述都必须针对其页面独一无二 |
内容类型模式
先识别文档类型——它决定描述的起始方式。
教程
以 “Step-by-step tutorial for...” 开头：
description: Step-by-step tutorial for building a time series dashboard with ecommerce data, including custom intervals, percentiles, and multi-layer visualizations.
故障排除页面
以 “Troubleshooting guide for...” 开头：
description: Troubleshooting guide for Graph API issues including missing results, slow performance, and noisy connections. Understand sampling strategies and limitations.
参考页面
在句子中自然地使用 “reference”（不要将其作为标签前缀）：
description: Compare visualization capabilities across Lens, TSVB, aggregation-based editors, Vega, and Timelion. Reference tables list supported chart types, features, and aggregations.
标准操作指南 / 流程页面
不使用标签前缀，以操作内容开头：
description: Add interactive filter controls to dashboards with Options lists, Range sliders, and Time sliders. Filter data dynamically and focus on specific segments.
概览 / 说明页面
以功能的作用及其价值开头：
description: Detect patterns in unstructured logs with Discover's pattern analysis. Categorize log messages, identify common structures, and filter out noise during troubleshooting.
反面示例
绝不使用带连字符的标签前缀：
# WRONG
description: Reference - Compare visualization capabilities...
description: Tutorial - Build time series dashboards...
description: Guide - Manage dashboards by searching...
绝不使用片段或不完整句子：
# WRONG
description: Dashboard creation and management.
description: How to configure alerts.
工作流程
对于每个文件：
- 读取前置元数据和正文开头约 30 行
- 识别文档类型（教程、操作指南、参考、故障排除、概览）
- 检查是否已有
description字段 - 撰写或改写描述，使其符合限制和对应类型的模式
- 验证长度不超过 200 个字符
- 编辑前置元数据，添加或更新
description字段
处理目录时，如果整个文件夹中的描述均已完整，也要跳过这些文件——只编辑缺少描述或描述质量不佳的文件。
报告
处理完毕后，总结：
- 已更新的文件（如有改写，列出旧描述 → 新描述）
- 已跳过的文件（已有合格描述）
- 仍缺少描述的文件（如有）
评论
支持 Markdown