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 ドキュメント向けのコンテンツタイプ準拠チェッカーです。次の 2 つのモードで動作します。
- 検証モード — 既存のページ（ファイルまたは貼り付けたコンテンツ）をコンテンツタイプのガイドラインに照らして評価し、準拠していない項目を報告します。
- 分類モード — まだ作成されていないページの短い説明を受け取り、最適なコンテンツタイプと、これから作成する必要がある必須要素を判断します。
入力
$ARGUMENTS は次のいずれかです。
- ファイルパスまたはディレクトリ → 検証モード
- 貼り付けたページコンテンツのブロック（フロントマターや Markdown の本文） → 検証モード
- 作成予定のコンテンツの短い説明（ファイルなし、本文全体なし） → 分類モード
空の場合は、何をチェックまたは分類するかユーザーに尋ねてください。
モードの判定
処理を進める前に、該当するモードを判断してください。
- 入力が既存のファイルパス、ディレクトリ、またはフロントマターや実質的な Markdown 本文を含む貼り付けコンテンツの場合は、検証モードです。
- 入力が仮想または作成予定のページの説明の場合は、分類モードです。一般的な表現には、「これはハウツーに当たるでしょうか？」「このアイデアを分類してください：…」「X についてページを書きたいのですが、どのコンテンツタイプがよいですか？」「概要とハウツーのどちらにすべきですか？」などがあり、実際のページコンテンツではなく意図を説明するプロンプトも該当します。
判断に迷う場合は、推測せず、要点を絞った質問を 1 つしてください。2 つのモードでは手順が異なります。検証モードではステップ 1〜4 を実行し、分類モードでは後述の分類モードの手順に従います。
ステップ 1：コンテンツタイプの検出
対象ファイルを読み込み、フロントマターに type フィールドがあるか確認してください。
---
type: overview
---
有効なコンテンツタイプ：overview、how-to、tutorial、troubleshooting、changelog。
type フィールドがない場合は、ページの構成と内容からコンテンツタイプを推測し、フロントマターに type フィールドがないことを記載してください。
ステップ 2：ガイドラインの取得
推奨：elastic-docs MCP
elastic-docs MCP サーバーの get_document_by_url ツールを使用し、includeBody を true に設定してガイドラインのページを取得してください。以下の表に記載されたガイドラインの URL を渡します。
取得した内容タイプのドキュメントと埋め込みチェックリストに食い違いがある場合は、取得したドキュメントを優先してください。取得した内容タイプのドキュメントに product の単数形と記載されていても、対象リポジトリで products のフロントマターが使われている場合は、正規のリポジトリスキーマに従い、出典間に不整合があることを記載してください。
フォールバック：WebFetch
MCP を利用できない場合は、ガイドラインとテンプレートを直接取得してください。LLM が読み取りやすいバージョンを取得するには、ガイドラインの URL に .md サフィックスを付けてください。
取得したコンテンツを使用して、必須要素、推奨セクション、ベストプラクティス、アンチパターンに照らし合わせてページを評価してください。
ステップ 3：ガイドラインに照らし合わせて評価する
取得したコンテンツタイプのガイドラインに照らしてページを確認してください。必須要素ごとに、含まれているか、正しく記述されているかを確認します。ベストプラクティスについては、違反があれば記録してください。
以下の現行チェックリストを、最低限のレビュー基準として使用してください。
共通のフロントマターとメタデータ
- ファイル名：コンテンツタイプに命名規則がある場合、それに一致していること。
- フロントマター：
descriptionと、リポジトリで標準となっている製品メタデータフィールドが含まれていること。docs-content ではproductではなくproductsを使用してください。 - タイトル：コンテンツタイプの目的に合致し、センテンスケースで、検索やナビゲーションに十分具体的であること。
- 導入文：ページが読者の目的に合っているか判断するのに役立つこと。
概要
- 目的：1つの概念、機能、製品、または能力について説明していること。
- 必須コンテンツ：それが何か、どのように機能するか、なぜ重要なのかを説明していること。
- 推奨コンテンツ：有用な場合は、ユースケースや例、仕組みの説明、次のステップ、関連ページを含めていること。
- アンチパターン：長い手順、別の場所に掲載すべきリファレンステーブル、重複するハウツーコンテンツを含めていないこと。
ハウツーガイド
- 目的：ユーザーが単独で完結する1つのタスクを実行できるよう支援すること。
- 必須コンテンツ：動作を示すタイトル、得られる成果を中心とした簡潔な導入文、始める前にまたは要件のセクション、番号付きの手順、成功を確認するためのチェックポイントを含めていること。
- 推奨コンテンツ：有用な場合は、次のステップや関連ページを含めていること。
- アンチパターン：広範な概念を解説したり、多くのタスクを連鎖させたり、理由なく全体の手順数が約10を超えたり、重要な操作の検証を省略したりしていないこと。
チュートリアル
- 目的：関連するタスクをつなげて、有意義な成果を目指す実践的な学習体験を提供します。
- 必須コンテンツ：学習目標、必要に応じて対象読者やスキル要件、前提条件とセットアップ手順、説明手順、確認ポイントや成果、コードが中心となる場合はコードの注釈、次のステップ、関連ページを含めます。
- 推奨コンテンツ：段階的に情報を提示し、現実的な例を使い、全体を通して検証手順を設けます。
- アンチパターン：範囲の狭い単一のレシピ、リファレンスページ、または実践を伴わない長い概念解説のような構成にはしません。
トラブルシューティング
- 目的：特定の、再現可能な問題を解決できるようユーザーを支援します。
- 必須コンテンツ：問題に焦点を当てたタイトル、症状セクション、解決方法セクションを含めます。
- 症状：ユーザーから見える動作のみを説明し、可能な場合は正確なエラーメッセージを含め、原因については触れません。
- 解決方法：よくある修正方法から順に、具体的で指示的な手順を提示します。必要に応じて、最小限の設定例を含めます。
- 任意のコンテンツ：同じ症状に複数の原因が考えられる場合に限り診断を、問題に直接関連する予防策に限りベストプラクティスを、補足資料に限りリソースを含めます。
- アンチパターン：特定の問題を扱うページに「トラブルシューティング X」のような一般的なタイトルを使ったり、関連のない問題を混在させたり、修正方法の前に長い説明を置いたりしません。
変更履歴
- 目的：リリースノートの生成に向けて、ユーザー向けの製品変更を1つ説明します。
- 必須コンテンツ：
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 フラグの機能と、1行の使用例を記載した短いページ」
説明が曖昧すぎて分類できない場合（参考になる語句が約10語未満で、意図を示す動詞がなく、明確な分野への言及もない場合）は、推測せずに、焦点を絞った確認質問を1つしてください。
ステップ 2（分類）：コンテンツタイプの定義と照合する
以下の定義を使用して、提案を各コンテンツタイプに照らして評価します（ページを採点する際に Validate モードで使用される定義です。完全なチェックリストについては上記のステップ 3 をご覧ください）。
- 概要 — 何であるか、どのように機能するか、なぜ重要かを説明します。概念を中心に扱い、長い手順やリファレンステーブルはアンチパターンです。
- ハウツー — 独立して完了できるタスクを 1 つ達成します。動作を表す動詞を使ったタイトル、「始める前に」または要件、番号付きの手順、成功を確認するチェックポイントを含みます。アンチパターン：複数のタスクを連鎖させる、または幅広い概念を教える。
- チュートリアル — 学習上の意義がある成果に向けて、関連するタスクを連鎖させます。目標、前提条件、説明の流れ、チェックポイントを含みます。アンチパターン：狭い範囲のレシピ、または概要のみの内容。
- トラブルシューティング — 繰り返し発生する特定の問題を解決します。問題に焦点を当てたタイトル、症状セクション、解決方法セクションを含みます。アンチパターン：一般的な「X のトラブルシューティング」という案内ページ、または無関係な問題の混在。
- 変更履歴 — リリースノート向けに、ユーザーに関係する 1 つの製品変更を説明します。動作を表す動詞を使ったタイトル、ユーザーへの影響に焦点を当てた内容、現在形を含みます。アンチパターン：実装に焦点を当てた説明、または曖昧な要約。
提案の説明が最も明確に示している定義のタイプを選びます。提案に手順が順番に記載されている場合は、概要よりもハウツーを優先します。エラーや症状に言及している場合は、ハウツーよりもトラブルシューティングを優先します。概念の導入や説明に言及している場合は、概要を優先します。
ステップ 3（分類）：確信度と構成を確認する
確信度を割り当てます。
- 高 — 提案が、あるタイプに必須のコンテンツを明確に示しています（例：手順と前提条件が明示されている場合はハウツー、症状と解決方法が明示されている場合はトラブルシューティング）。
- 中 — 最も適しているタイプはあるものの、必須要素が不足している場合、または 2 つのタイプに部分的に当てはまる場合です。ユーザーにアウトラインの作成と再分類を提案します。
- 低 — どのタイプにも明確に当てはまりません。新しいページではなく、既存ページのセクションとして追加するほうが適切な可能性があります。新しいページとして扱う前に、関連ページを確認するよう勧めます。
ステップ 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)>
どのタイプにも明確に当てはまらない場合（すべてのタイプで確信度が低い場合）は、その旨を明記し、新しいページを作成するのではなく、既存ページに新しいセクションとして追加できるかを確認するよう勧めます。無理に当てはめないでください。