documentation-standards について
documentation-standardsは、ドキュメントの作成者やレビュー担当者向けのスキルです。LLM向けの構成、機械可読な仕様、PandocによるPDF変換の基準を定めています。
主な機能
- 01LLM向けドキュメント構成
- 02ハブとスポークによる情報整理
- 03Markdownの見出しと書式ルール
- 04機械可読な仕様の指針
- 05PDF互換性チェックリスト
活用シーン
- 01MarkdownのガイドやREADMEの作成
- 02文書の書式一貫性のレビュー
- 03PandocでPDF化するMarkdownの準備
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/documentation-standardsを入力して読み込まれたか確認します。
同梱ファイルreferences/evolution-log.md
詳細
ドキュメントの標準
自己進化型スキル：このスキルは使用を通じて改善されます。指示に誤りがある場合、パラメーターにずれが生じた場合、または回避策が必要になった場合は、先送りせず、このファイルをすぐに修正してください。実際に再現可能な問題がある場合にのみ更新してください。
概要
LLM による利用と、Pandoc を使用したプロフェッショナルな PDF への変換の両方に最適化された Markdown ドキュメントを作成するための標準です。すべてのドキュメントで一貫性を確保します。
このスキルを使用するタイミング
次の場合に使用します：
- Markdown ドキュメント（README、スキル、ガイド、仕様書）を作成するとき
- Markdown コンテンツを含む新しいスキルを作成するとき
- PDF に変換される可能性があるコンテンツを作成するとき
- ドキュメントが標準に準拠しているか確認するとき
基本原則
1. LLM に最適化されたドキュメントアーキテクチャ
機械可読性の優先：OpenAPI 3.1.0 仕様、JSON Schema、YAML 仕様を人間向けドキュメントより優先します。
理由：構造化形式は、人間と LLM の両方が確実に利用できる、曖昧さのない契約を提供します。人間向けドキュメントは機械可読な仕様を補足するものであり、置き換えるものではありません。
適用方法：
- ワークフロー仕様 → specifications/ 内の OpenAPI 3.1.1 YAML
- データスキーマ → 例を含む JSON Schema
- 設定 → 検証スキーマを備えた YAML
- 人間向けドキュメント → 正式な機械可読仕様を参照する Markdown
2. ハブ＆スポークによる段階的な情報開示
パターン：中央のハブ（CLAUDE.md、INDEX.md など）から、詳細なスポーク（スキル、ドキュメントディレクトリなど）にリンクします。
構造：
CLAUDE.md (Hub - Essentials Only)
↓ links to
Skills (Spokes - Progressive Disclosure)
├── SKILL.md (Overview + Quick Start)
└── references/ (Detailed Documentation)
ルール：
- ハブには要点（何がどこにあるか）のみを記載します
- スポークには段階的な詳細を記載します（必要に応じて読み込みます）
- トピックごとに唯一の情報源を設けます（重複させません）
3. Markdown のセクション番号
重要なルール：Markdown の見出しに手動で番号を付けないでください。
❌ 誤り：
## 1. Introduction
### 1.1 Background
### 1.2 Objectives
## 2. Implementation
✅ 正しい：
## Introduction
### Background
### Objectives
## Implementation
理由：
- PDF の生成時に、Pandoc の
--number-sectionsフラグがすべてのセクションに自動で番号を付けます - 手動で番号を付けると重複が生じ、レンダリング後に「1. 1. はじめに」のようになります
- 自動採番は一貫性があり、セクションの並べ替えに応じて自動で更新されます
- すべての Markdown に適用されます：ドキュメント、スキル、プロジェクトファイル、README ファイル
ルール：Markdown が PDF に変換される可能性がある場合、見出しに手動で番号を付けないでください。意味に応じた見出しレベル（##、###）を使用し、番号付けはツールに任せてください。
標準チェックリスト
ドキュメントの作成時またはレビュー時に、このチェックリストを使用してください：
構造
- ハブ＆スポークのパターンに従っている（主要ドキュメントには要点、詳細は参照先に記載）
- 段階的な情報開示のため、より詳細なドキュメントへのリンクがある
- 唯一の情報源が保たれている（ドキュメント間で内容が重複していない）
Markdown の書式設定
- 見出しに手動でセクション番号を付けていない
- 意味に応じた見出しレベル（##、###、####）を正しく使用している
- コードブロックに構文強調表示用の言語識別子がある
- リンクに、裸の URL ではなく Markdown 形式の
[text](url)を使用している
機械可読なコンテンツ
- ワークフローを OpenAPI 3.1.1 仕様として記述している（該当する場合）
- データ構造に JSON Schema を使用している（該当する場合）
- 設定に検証機能付きの YAML を使用している（該当する場合）
- 人間向けドキュメントで正式な機械可読仕様を参照している
ファイル構成
- ドキュメントが適切な場所に配置されている：
- グローバル標準 → docs/standards/
- スキルのドキュメント → skills/{skill-name}/references/
- プロジェクトのドキュメント → {project}/.claude/ または {project}/docs/
- インデックスファイルでナビゲーションを提供している（INDEX.md、README.md）
関連リソース
- ASCII 図の検証：ascii-diagram-validator - Markdown 内の ASCII 図を検証します
- スキルアーキテクチャ：効果的なスキルの作成については、skill-architecture プラグインを参照してください
例
良いハブ＆スポーク構造
ハブ（CLAUDE.md）：
## PDF Generation from Markdown
**Quick Start**: Use pandoc-pdf-generation skill
**Critical Rules**:
1. Never write ad-hoc pandoc commands
2. Always verify PDFs before presenting
3. See skill for detailed principles
スポーク（skill/SKILL.md）：
- 例を含むクイックスタート
- 詳細なドキュメントについては references/ へのリンク
- 必要に応じた段階的な情報開示
機械可読性に優れたドキュメント
ワークフロー仕様（specifications/hook-prompt-capture.yaml）：
openapi: 3.1.1
info:
title: Hook Prompt Capture Workflow
version: 1.0.0
paths:
/capture-prompt:
post:
summary: Capture user prompt from hook
# ... detailed spec
人間向けドキュメント（README.md）：
## Workflow
See [hook-prompt-capture.yaml](./specifications/hook-prompt-capture.yaml)
for complete workflow specification.
Quick overview: ...
概要
ドキュメント標準により、以下が実現します。
- ワークスペース内のすべてのドキュメントの一貫性
- 機械可読形式によるLLM 向けの最適化
- ハブ・アンド・スポーク方式と信頼できる唯一の情報源による保守性
- 適切な Markdown 形式によるPDF 互換性
すべてのドキュメントで、これらの標準に従ってください。
トラブルシューティング
| 問題 | 原因 | 解決策 |
|---|---|---|
| PDF のセクション番号が重複する | Markdown で手動で番号を付けている | 手動の番号を削除し、--number-sections のみを使用する |
| PDF のリンクが壊れている | 相対パスが正しくない | ドキュメント間リンクにはリポジトリルートからのパスを使用する |
| コードブロックに構文色が付かない | 言語識別子がない | 開始の三連バッククォートの後に言語を追加する |
| テーブルの表示が崩れる | 列幅が広すぎる | 見出しを短くするか、パイプテーブル形式を使用する |
| ハブドキュメントが長すぎる | ハブに詳細を詰め込みすぎている | 詳細をスポークドキュメントに移し、ハブからリンクする |
| 内容が重複している | 同じ情報が複数のドキュメントにある | 信頼できる唯一の情報源を特定し、重複を削除してリンクを追加する |
| YAML 仕様が表示されない | ファイル拡張子が間違っている | OpenAPI 仕様には .yaml 拡張子を使用する |
| インデックスのナビゲーションがない | INDEX.md または README.md がない | 各ディレクトリにナビゲーションインデックスを作成する |
実行後の振り返り
このスキルの実行後、終了する前に以下を確認してください。
- コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった指示またはエラーテーブルを修正してください。
- パラメーターまたは出力に変更がありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、それに合わせて使用例とパラメーターテーブルを更新してください。
- 回避策が必要でしたか？ — 即興で対応した場合（異なるフラグや追加手順など）は、次回の実行で同じ回避策が不要になるように、この SKILL.md を更新してください。
問題が実際に発生し、再現可能な場合にのみ更新してください。推測に基づく更新はしないでください。