documents

ドキュメント — PDF、Word、Excel、PowerPoint スキル

最も一般的な4種類のドキュメント形式を扱う単一のスキルです。4種類すべてで、同じエージェントのワークフロー（構造化されたコンテンツを入力し、レンダリング可能で検証済みの成果物を出力）を共有するため、epub の先例にならい、形式ごとのリファレンスを備えた1つのファミリースキルとしてまとめています。以下の共通ワークフローを読み込んでから、実際に扱う形式に対応するリファレンスを読み込んでください。

形式	拡張子	リファレンス（必要に応じて読み込み）
PDF	.pdf	references/pdf.md
Word	.docx	references/word.md
Excel	.xlsx	references/excel.md
PowerPoint	.pptx	references/powerpoint.md
すべての形式	—	references/output-quality.md

各形式の生成テンプレートは templates/ にあり、形式ごとのフィクスチャを含む検証スクリプトは scripts/ にあります。

使用する場面

以下の4種類の形式のいずれかに関わるタスクで、このスキルを読み込んでください。

• 生成：構造化されたコンテンツ（Markdown、JSON、データテーブル、アウトライン）から、レポート、メモ、スプレッドシート、スライド資料を作成します。
• 編集：既存のドキュメントのコンテンツ、レイアウト、メタデータをその場で変更します。
• 抽出：既存のファイルからテキスト、表、構造を取り出します。
• 変換：形式間、またはデータソースからドキュメントへコンテンツを移します。
• 検証：生成した成果物の構造が正しく、納品前に意図どおりレンダリングされることを確認します。

使用しない場面

• 電子書籍と EPUB — epub スキルを使用してください。EPUB コンテナー、読み上げ順序、パッケージの検証を扱います。
• 画像、動画、その他のメディア — このスキルが扱うのはドキュメント形式のみです。メディアの制作は適切なメディアスキルに振り分けてください。
• コードと API ドキュメントサイト — オフィスドキュメントではなく、技術ドキュメントおよびドキュメントサイトの規約を使用してください。
• データパイプライン — 生データの移動や変換には data-engineering を使用してください。ここでの Excel は納品形式であり、データストアではありません。
• オフィスドキュメントから Markdown への変換 — 既存のオフィスドキュメント（docx、xlsx、pptx、pdf、odt、rtf、epub、csv）を GitHub-Flavored Markdown に変換する場合は、anydoc スキルを使用してください。このスキルが扱うのは生成、編集、検証であり、ドキュメントから Markdown への抽出ではありません。

共通ワークフロー

形式にかかわらず、すべてのドキュメントタスクは同じ6つのステップに従います。形式固有の詳細は形式別のリファレンスに記載されているため、必要なステップで参照してください。

1. スコープ

ファイルに触れる前に、ドキュメントの用途を明確にします。

• 対象読者と目的 — 誰が読むのか、また、どのような判断に役立てるのか。
• 形式 — PDF（固定レイアウト、印刷、アーカイブ）、Word（編集可能な文章、レビュー）、Excel（データ、計算）、PowerPoint（プレゼンテーション）。
• 制約 — ページ数／スライド数、サイズ制限、ブランドやスタイルの制約。
• 信頼できる情報源 — ドキュメントの生成元となる構造化コンテンツ（Markdown、JSON、CSV、アウトライン）。これにより成果物を再現できます。

2. コンテンツモデル

レンダリングする前に、ドキュメントのコンテンツを構造化データとして表現します。

• 文章主体のドキュメントでは、タイトル、セクション／見出し、本文、メタデータを用意します。
• スプレッドシートでは、テーブルモデル（ヘッダー、行、列の型）を用意します。
• スライド資料では、スライドのアウトライン（各スライドのタイトルと箇条書き、発表者ノート）を用意します。
• コンテンツとレイアウトを分離します。コンテンツはモデルに、レイアウトはテンプレートに保持します。これにより、再生成のコストを抑えられます。

3. テンプレート

templates/ から、対象形式の生成テンプレートを選択します。

• templates/pdf-template.md — 固定レイアウトの ドキュメントの骨組み（印刷用 HTML/CSS または LaTeX のソース）。
• templates/word-template.md — ワープロ ドキュメントの構造（スタイル、見出し、表）。
• templates/excel-template.md — ワークブックの 構造（シート、セル、共有文字列、数式）。
• templates/powerpoint-template.md — スライド デッキの構造（スライド、レイアウト、ノート）。

コンテンツモデルの内容で、テンプレートの [fill: ...] マーカーを埋めます。テンプレートはコンテンツとレイアウトの間の契約です。テンプレートを変更すれば、コンテンツに手を加えずに見た目を変更できます。

4. レンダリング

成果物ファイルを作成します。

• PDF — テンプレートを PDF にレンダリングします（ブラウザーまたはエンジンでの印刷用 CSS、あるいは LaTeX ツールチェーンを使用）。ツールについては references/pdf.md を参照してください。
• Word / Excel / PowerPoint — OOXML パッケージを直接（小規模な成果物には標準ライブラリの zipfile + XML を使用）または形式に対応する一般的なライブラリ（python-docx、openpyxl、python-pptx）で書き込みます。生成するパッケージの正確なレイアウトについては、形式ごとのリファレンスを参照してください。

5. 検証

検証していない出力を納品してはいけません。検証スクリプトを実行します。

python3 scripts/validate-documents.py --render-check --json report.pdf brief.docx data.xlsx deck.pptx

このスクリプトは構造の健全性チェック（コンテナのシグネチャ、必須パーツ、XML の整形式性）と、レンダラーがインストールされている場合はレンダリングチェック（ファイルを実際にレンダリング）を実行します。レンダラーが存在しない場合は失敗ではなく unavailable と報告します。検証でレンダラーが必須になることはありません。出力品質のチェックリスト全体については references/output-quality.md を参照してください。また、スクリプト自体のスモークテストには、形式ごとに用意された fixtures/ 内のフィクスチャファイルを使用してください。

python3 scripts/validate-documents.py --json fixtures/sample.pdf fixtures/sample.docx fixtures/sample.xlsx fixtures/sample.pptx

6. 納品

成果物とともに、その来歴を引き継ぎます。

• ソースコンテンツモデル（再生成できるようにするため）。
• 使用したテンプレートのバージョン。
• 検証結果（構造チェックに合格したこと、レンダリングを確認したか、または利用できなかったか）。
• 既知の差異（フォントの代替、画像の縮小、レイアウトのずれ）。

完了条件

成果物が存在し、構造検証に合格し（レンダラーが利用可能な場合はレンダリングチェックにも合格し）、コンテンツが合意した範囲に一致した時点で、タスクは完了です。検証済みの成果物とその来歴を納品したら終了してください。新たに範囲の指示がない限り、レイアウトの反復を続けないでください。

スクリプト

すべてのスクリプトは、このスキルのディレクトリからの相対パスで scripts/ に配置され、cli-builder の規約に従います。機械処理用の出力には --json を指定し、対話形式ではなく、エラーは stderr に出力します。フラグの詳細を確認するには --help を指定して実行してください。

validate-documents.py — 構造の健全性チェック + レンダリングチェック

python3 scripts/validate-documents.py report.pdf            # human report
python3 scripts/validate-documents.py --json report.pdf    # machine report
python3 scripts/validate-documents.py --render-check --json report.pdf data.xlsx deck.pptx

動作：

• 形式ごとの構造の健全性チェック：PDF ヘッダー／EOF／ページオブジェクト、OOXML ZIP コンテナ、[Content_Types].xml、必須パーツ、XML の整形式性。 レガシーな .doc/.xls/.ppt ファイルは OLE2 のマジックバイトで識別します。
• レンダリングチェック（--render-check）：PDF は pdftoppm／mutool／gs で、Office 形式は LibreOffice でレンダリングします。レンダラーがインストールされていない場合は unavailable と報告して終了コード 0 を返します（正常に縮退し、クラッシュすることはありません）。
• 終了コード：すべて合格（またはレンダリングチェックが利用不可）の場合は 0、ファイルが構造またはレンダリングのチェックに失敗した場合は 1、使用方法または I/O エラーの場合は 2。
• JSON 出力：ファイルごとのチェックとレンダリング結果を含むトップレベルの status（ok / fail / unavailable / error）。

関連スキル

• epub — 電子書籍コンテナのスキル。この形式ファミリーにおける兄弟スキルの先例です。
• data-engineering — データパイプラインと変換に関するスキル。ここでは Excel はデータストアではなく、納品形式です。
• cli-builder — 検証スクリプトが従う CLI 規約（--json、非対話形式、終了コード）。