docs-frontmatter-description について
Elastic ドキュメントの YAML frontmatter にある description を作成・改善するスキルです。ページ種別ごとの書き方に沿って、簡潔で事実に基づき検索しやすい説明を確認します。
主な機能
- 01ページ種別に合わせた説明文の作成
- 02長さ、語調、表現のルール
- 03チュートリアルやリファレンスを区別
- 04description の確認と結果報告
活用シーン
- 01ページ用の検索説明文を作成
- 02規約に合わない説明文を修正
- 03Markdown ファイル群の説明文を確認
- 04文書種別に応じて説明文の調子を統一
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/docs-frontmatter-descriptionを入力して読み込まれたか確認します。
同梱ファイルevals/evals.json
詳細
Elastic ドキュメント向けのメタディスクリプションを作成します。検索エンジンで見つけやすくなるように、Elastic の規約に従って YAML フロントマターの description フィールドを新規作成または改善してください。
入力
$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フィールドを追加または更新します
ディレクトリを処理する場合、フォルダー内のすべてのファイルに説明文がすでに揃っているときは、そのフォルダーをスキップしてください。説明文がないファイル、または内容が不十分なファイルのみを編集します。
レポート
処理後、次の内容をまとめます。
- 更新したファイル（書き換えた場合は、古い説明文 → 新しい説明文）
- スキップしたファイル（すでに適切な説明文があったもの）
- 説明文がないままのファイル（残っている場合）