diataxis について
diataxisは、Diátaxisフレームワークに基づき、文書の分類、監査、生成、再構成を行うドキュメントガバナンス用スキルです。文書の保守担当者やエージェント向けに、チュートリアル、ハウツー、リファレンス、解説を区別します。
主な機能
- 014つの象限に文書を分類
- 02不足や混在した内容を監査
- 03象限に沿った文書の生成
- 04内容タイプごとに文書を再構成
- 05生成前に象限の確認を要求
活用シーン
- 01既存ページの文書タイプを判定
- 02文書セット全体の不足を発見
- 03指定した象限のコンテンツを起草
- 04用途が混在する文書の分割を計画
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/diataxisを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
references/anti-patterns.mdcompass.mdquadrants.md詳細
Diátaxis ドキュメントガバナンス
このスキルは、ドキュメントに Diátaxis フレームワークを適用します。Diátaxis では、ユーザーのニーズに基づいて、ドキュメントを チュートリアル、ハウツーガイド、リファレンス、解説の 4 種類に分類します。それぞれ目的が異なり、書き方も変える必要があります。
動作モード
このスキルは、次のいずれかのモードで動作します。
- classify：コンテンツがどの象限に属するかを特定します
- audit：ドキュメント群の不足、偏り、違反を分析します
- generate：指定された象限に沿って新しいドキュメントを作成します
- restructure：既存の複数モードが混在したコンテンツを分割または再編成します
モードはユーザーのリクエストから推定するか、明示的に指定する必要があります。動作モードを確信を持って推定できない場合は、作業に進む前に確認を求めてください。
象限の純粋性を維持できない場合、説明を添えて拒否することも、有効かつ適切な結果です。
Generate モードのポリシー
generate モードでは、コンテンツを作成する前に、次のいずれかを満たす必要があります。
- ユーザーが対象の象限を明示している（「X のハウツーを書いてください」など）、または
- エージェントがリクエストを分類し、確信度と根拠を示して説明したうえで、ユーザーの確認を得ている
Diátaxis の指針
次の判断ツリーを使い、コンテンツを必ず 1 つの象限に分類してください。
| コンテンツが… | そして、ユーザーの…に役立つ場合 | …に属します |
|---|---|---|
| 行動を促す | 習得（学習） | チュートリアル |
| 行動を促す | 適用（作業） | ハウツーガイド |
| 認知を促す | 適用（作業） | リファレンス |
| 認知を促す | 習得（学習） | 解説 |
確認する 2 つの質問：
- これは 行動（実行）を促しますか、それとも 認知（理解）を促しますか？
- これは 習得（学習）に役立ちますか、それとも 適用（作業）に役立ちますか？
象限の概要
チュートリアル（学習志向）
学習者を実践的な体験へと導くレッスンです。学習者の成功に対する責任は指導者が負います。説明ではなく、実践に重点を置きます。早い段階から、何度も成果を得られるようにします。説明は最小限にします。選択肢や代替案は提示しません。
- 形式：具体的な手順を順番に進めるレッスン
- 言葉遣い：「一緒に…しましょう」「まず、X を実行します」「…に気づくでしょう」
- 該当しないもの：概念の指導、代替案の提示、理由の説明
ハウツーガイド（目標志向）
実際の問題を解決するために、すでに十分な知識を持つユーザーを導く手順です。読者が達成したいことを把握している前提です。学習ではなく、作業に重点を置きます。
- 形式：特定の目標に対応する一連の手順
- 言葉遣い：「X を達成するには、Y を実行します」「…したい場合は」「条件付きの命令」
- 該当しないもの：初心者向けの指導、概念の説明、仕組みの解説
リファレンス（情報志向）
仕組みに関する技術的な説明です。簡潔かつ中立的で、正確さを重視します。構成は説明対象そのものに沿います。ユーザーは通読するのではなく、必要な情報を参照します。
- 形式：構造化された説明、表、仕様
- 言葉遣い：「X は…です」「選択肢は…です」、事実に基づく記述
- 該当しないもの：手順の指示、理由の説明、物語調の記述、意見
解説（理解志向）
背景や文脈を示し、「なぜ」に答える論述です。関連性を示し、意見を交え、さまざまな角度からテーマを掘り下げます。
- 形式：テーマについての散文による考察
- 言葉遣い：「X の理由は…です」「これは…だからです」「…を考えてみましょう」
- 該当しないもの：段階的な手順、技術仕様、作業の指導
基本ワークフロー
分類する場合
- コンテンツを注意深く読む
- 指針を適用する：行動／認知 × 習得／適用
- 該当する象限を 1 つ特定する
- 確信度と根拠を示して報告する
生成の場合
- 対象の象限を確認します（明記されているか、推定したうえで確認します）。
- 象限の制約を厳密に適用します。
- 象限を混在させないでください。必要に応じて分割を提案します。
- 出力が象限の特性に沿っているか検証します。
監査の場合
- すべてのドキュメントを一覧にします。
- 各ドキュメントを分類します。
- 不足している象限を特定します。
- 違反（モードの混在、誤った象限）を指摘します。
- 偏りを報告します（例：「リファレンスに偏り、チュートリアルが不足」）。
再構成の場合
- 既存のコンテンツを分類します。
- 象限の違反を特定します。
- 分割案を提示します（象限ごとに1つのドキュメント）。
- 変更を行う前に、ユーザーの確認を求める計画を提示します。
出力要件
分類または違反を指摘する際は、必ず次の項目を提示してください。
- 象限：特定した種類（チュートリアル、ハウツー、リファレンス、解説）
- 確信度：高 | 中 | 低
- 根拠：具体的なフレーズ、構成パターン、または手がかり
例：
ハウツー（確信度：高）として分類しました。 根拠：「configure」「set up」などの命令形の動詞、目標指向の見出し、概念的な説明がないこと、読者の知識を前提としていること。
違反の検出
次のアンチパターンを指摘してください。
- 解説を含むチュートリアル：「なぜ」に関する長いセクションや、概念的な脱線
- 教えるハウツー：初心者向けの説明、「学んでみましょう」といった表現
- ストーリーを含むリファレンス：一人称の文体、手順に沿った指示
- 手順を含む解説：番号付きの手順、命令形のコマンド
- モードが混在するドキュメント：1つのドキュメントに複数の象限を示す手がかりがある
詳細な検出パターンと改善方法については、references/anti-patterns.md を参照してください。
対象外
このスキルでは、次のことは行いません。
- ドキュメント戦略や情報アーキテクチャを新たに考案する
- 製品アーキテクチャや機能範囲を決定する
- 複数の Diátaxis の象限を1つのドキュメントに統合する
- リポジトリ固有のドキュメントルールやスタイルガイドに優先する
- 明示的な象限分類なしにコンテンツを生成する
追加リソース
- 象限の詳細な特性：references/quadrants.md
- 分類の決定木：references/compass.md
- アンチパターンと対処法：references/anti-patterns.md
クレジット
Diátaxis は Daniele Procida によるものです。このスキルは、AI エージェントが Diátaxis フレームワークを利用できるようにするものです。正式な情報源と完全なドキュメントについては、diataxis.fr を参照してください。
CC-BY-SA 4.0 の下でライセンスされています。引用メタデータは Diátaxis GitHub リポジトリで入手できます。