mcpField
D
docs-frontmatter-audit

docs-frontmatter-audit

github.com/elasticドキュメント72150 回インストール2 日前に更新
リポジトリ

docs-frontmatter-audit について

docs-frontmatter-audit は、Elastic ドキュメントの Markdown ファイルにある frontmatter を確認するスキルです。必須フィールドと説明文を検証し、問題の種類ごとに構造化レポートへまとめます。

主な機能

  1. 01指定範囲の Markdown ファイルをスキャン
  2. 02必須の `products` エントリーを確認
  3. 03説明文を検証
  4. 04ナビゲーションタイトルがない長い H1 を指摘
  5. 05問題の種類ごとに結果を整理

活用シーン

  1. 01ドキュメントディレクトリの frontmatter 監査
  2. 02レビュー前の製品 ID と説明文の確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/elastic/elastic-docs-skills --skill docs-frontmatter-audit

インストール後、Claude Code で/docs-frontmatter-auditを入力して読み込まれたか確認します。

同梱ファイルevals/evals.json

詳細

Elastic ドキュメントのフロントマター監査担当です。指定された範囲内のすべての Markdown ファイルを確認し、フロントマターが完全かつ正確かを検証してから、構造化されたレポートを作成します。

入力

$ARGUMENTS は、監査対象のファイルパスまたはディレクトリです。空の場合は、ユーザーに監査対象を尋ねます。

ユーザーから別の設定が指定されない限り、以下の設定をデフォルトとして使用します。必要なキーまたは製品が対象範囲によって曖昧になる場合にのみ、確認を求めます。

設定デフォルト説明
必須の products(なし)含める必要がある製品 ID（例：kibana）
追加の製品を許可はい必須の製品 ID 以外の製品 ID を許容するかどうか

必須のフロントマター要素

各ファイルについて、以下の要素を確認します。

1. products（必須）

設定された必須の製品 ID が含まれている必要があります。追加の製品を含めることもできます。docs-content では、正式なフロントマターフィールドは products で、id エントリーを使用します。取得したコントリビューター向けドキュメントに単数形の product と記載されている場合は、ソースの不整合として扱い、docs-builder および現在の docs-content ページで使用されている正式な products の形式に従います。

products:
  - id: kibana

この要素がないファイル、または必須の製品が欠けているファイルを指摘します。既存の追加の製品は削除しないでください。 単数形の product は、ローカルリポジトリで明示的にその形式が使用されていない限り、誤りの可能性が高いものとして指摘します。

2. description（必須）

以下のルールに照らして検証します。

  • 存在し、空ではない
  • 約150文字（docs-builder 推奨）。200文字を超える場合は長すぎると指摘する
  • 完全文である（断片やラベルではない）
  • Jinja2 の置換変数を含まない（{{kib}}、{{es}}、{{esql}} はフロントマターでは解析されません）
  • ラベルの接頭辞がない（「Reference -」「Tutorial -」「Guide -」）
  • ページの内容を明確に要約し、ユーザーに伝わる内容である
  • YAML で誤読される可能性のある句読点や文字（コロンなど）が含まれる場合は、引用符で囲まれている
3. navigation_title（推奨）

H1 のタイトルが約50文字を超えるか確認します。超える場合は、navigation_title を追加するよう指摘します。

navigation_title: "Configure ML alerts"
4. mapped_pages（維持）

存在する場合は、指摘したり変更を提案したりしないでください。存在しない場合も、追加を提案しないでください。

実行

  1. 指定された範囲内のすべての .md ファイルをグロブで検索します
  2. 各ファイルのフロントマターを読み取ります
  3. 上記のルールに照らして各要素を検証します
  4. H1 タイトルを読み取り、navigation_title が必要か確認します
  5. レポートを作成します

レポート形式

## Frontmatter audit: <scope>

**Configuration:**
- Required products: kibana
- Files scanned: N

### Issues found

#### Missing `products`
| File | Issue |
|------|-------|
| path/to/file.md | Missing `kibana` product |

#### Invalid or missing `description`
| File | Issue |
|------|-------|
| path/to/file.md | Missing description |
| path/to/other.md | Contains Jinja2 variables |
| path/to/third.md | Exceeds 200 characters (247 chars); descriptions should usually be around 150 characters |

#### Missing `navigation_title`
| File | H1 length |
|------|-----------|
| path/to/file.md | 63 chars |

### Summary

- ✅ N files passed all checks
- ❌ N files have issues
  - N missing products
  - N invalid/missing description
  - N missing navigation_title (recommended)

問題はファイルごとではなく種類ごとにまとめ、関連する問題をまとめて修正できるようにします。問題があるセクションのみ記載します。

コメント

Markdown 対応