document-docx

ドキュメント DOCX スキル - クイックリファレンス

このスキルでは、専門的な .docx の用途である docxtpl のテンプレートパイプライン、python-docx による構造編集と抽出、LLM/RAG への取り込み、アクセシビリティ/EAA への準拠を扱います。

適用範囲： Anthropic 公式の docx スキルが利用できる場合、通常の作成・編集（docx-js）、validate.py を使った <w:ins>/<w:del> による変更履歴（赤字修正）の作成、コメントの作成には、そちらを優先してください。ユーザーが形式を指定せずに「ドキュメント」を求めており、ドキュメントコネクターまたはアーティファクトタイプが利用可能な場合は、.docx の生成よりそちらを優先してください。

基本的な判断ルール

• Word でレイアウトを担当するのは開発者以外で、コードはデータを提供する場合：docxtpl。コードで構造を決める場合：python-docx（Python）または docx（Node）。
• テンプレートのレンダリングはフェイルクローズにします。docxtpl はデフォルトでは欠落した変数を空欄としてレンダリングし、&/< をエスケープせずに挿入するため、ファイルは問題なく開けてタグスキャンにも合格します。scripts/docx_render_template.py（StrictUndefined + autoescape）を使用してください。references/template-workflows.md を参照してください。
• 変更履歴：高水準ライブラリでのサポートを決して約束せず、色や取り消し線で赤字修正を偽装しないでください。作成には公式 docx スキルの OOXML ワークフローを使用してください。references/tracked-changes.md を参照してください。
• 信頼できるファイルからセマンティック HTML を生成する場合：mammoth を使い、その後サニタイズします（mammoth はサニタイズを行いません）。RAG 用の Markdown/JSON には、Markdown コンバーターまたは scripts/docx_extract.py を使用してください。references/llm-extraction-workflows.md を参照してください。
• KB またはインデックスに取り込む DOCX：コンテンツコントロール内の表は Document.tables から検出されず、画像として貼り付けられた表にはテキストがなく、変更履歴には明示的な承認／原文のポリシーが必要で、ファイル名が実態と異なる場合もあります。ファイルをインデックス化する前に、references/docx-extraction-failure-modes.md にある表の数の検出チェックを実行してください（DOCX が取り込み対象の入力の場合は、必ず読み込んでください）。
• PDF 出力：最高品質を求める場合は Word の自動化、CI とバッチ処理には LibreOffice のヘッドレスモードを使用します。
• .doc：まず .docx に変換してください。.docm/.dotm：マクロは信頼できないものとして扱い、決して実行しないでください。
• .docx は編集可能なソースで、PDF はリリース用アーティファクトです。

クイックリファレンス

タスク	ツール	使用する場面
テンプレートへの入力、差し込み印刷	docxtpl + scripts/docx_render_template.py	Word で作成したテンプレート、文書の一括生成
Python での構造編集	python-docx (references/docx-patterns.md)	スタイル、表、セクション、フィールド、ハイパーリンク
コメント	python-docx の add_comment（バージョン依存）または公式 docx スキル	リビジョンを付けずにレビューコメントを追加
DOCX から HTML への変換	scripts/docx_to_html.mjs 経由の mammoth	信頼できる文書、セマンティック HTML
DOCX から JSON/Markdown への変換	scripts/docx_extract.py、Markdown コンバーター	自動化、RAG への取り込み
リビジョン／コメントの検査	scripts/docx_inspect_ooxml.py	レビュー済み文書を編集する前
リリースゲート	scripts/docx_quality_gate.py	生成または編集したすべてのファイル
DOCX から PDF への変換	Word の自動化／LibreOffice のヘッドレスモード	リリース用アーティファクト、CI のスモークテスト

形式と安全性に関する注意事項

• python-docx のコメント：本文のみが対象です。ヘッダーやフッターにはアンカーを設定できず、スレッド形式の返信や解決済み状態にも対応していません。また、アンカーはラン全体に設定されます。
• python-docx は、変更履歴の作成、代替テキストのプロパティ、フィールド API、公開されたハイパーリンク作成 API に対応していません。参考資料にある回避策では非公開属性を使用しているため、アップグレード後に必ず再検証してください。
• 目次やその他の Word フィールドは、Word で更新するか、LibreOffice でレンダリングするまで空欄または古い内容のままです。
• 新規作成した python-docx 文書は、デフォルトのテンプレートから作成者、日付、コメントを引き継ぐ場合があります。配布前にコアプロパティを確認してください。

機能を約束する前にバージョンを確認する

環境に最新のライブラリがあるとは限りません。

• Document.add_comment() は最近追加された python-docx の機能であり、古いバージョンでは AttributeError が発生します。コメント機能に対応していると約束する前に、hasattr(docx.document.Document, "add_comment") を確認してください。
• ここで未対応とされている機能（python-docx での変更履歴の作成、スレッド形式の返信、解決済みコメント）をユーザーから求められた場合は、その旨を明確に伝え、公式の docx スキルを案内してください。書式設定で代用しないでください。

デフォルトのワークフロー

1. ファイルの種類と信頼レベルを特定します。.docx／.dotx、.docm／.dotm、または旧形式の .doc` のいずれかです。
2. ドキュメントにレビュー用メタデータが含まれている可能性がある場合は、最初に scripts/docx_inspect_ooxml.py --json を実行します。
3. 生成または編集します。構造には docxtpl を通じて docx_render_template.py を使うか、python-docx／docx を使います。
4. 新しく生成した出力では、doc.core_properties に意図した作成者を設定し、テンプレートのコメントを削除して、created／modified を datetime.now(timezone.utc).replace(tzinfo=None) に設定します（python-docx はタイムゾーン情報のない UTC を想定します）。既存ファイルを編集する場合は、ユーザーがメタデータのリセットを求めていない限り、来歴を保持してください。
5. scripts/docx_quality_gate.py を実行します。--check-libreoffice が要求されていて実行できなかった場合も含め、問題があれば終了コード 2 になります。
6. 画像にレンダリングし、納品前に全ページを確認します。soffice --headless --convert-to pdf out.docx && pdftoppm -png -r 80 out.pdf page を実行し、page-*.png ファイルを開いてください。外部に配布する場合は、Word でも確認し、アクセシビリティチェックリストを適用してください。

python3 scripts/docx_render_template.py template.docx context.json out.docx   # exit 2 on missing vars
python3 scripts/docx_quality_gate.py out.docx --json                          # exit 2 on any issue
python3 scripts/docx_extract.py in.docx --include headers footers comments --out extracted.json
node scripts/docx_to_html.mjs in.docx out.html --style-map map.txt --extract-images-dir assets/

ラウンドトリップのリリース検証

• 最終保存の前に、セクション、表、画像、ハイパーリンク、コメント、変更履歴の想定数を記録します。
• 保存した DOCX を再度開き、各項目の数を比較します。
• コピーをレンダリングし、改ページ、番号付け、表のはみ出し、フォントの欠落、未解決のタグを確認します。

OOXML の解析やテキスト抽出が成功しても、レイアウトの忠実性が証明されるわけではありません。PDF が見た目どおりでも、編集可能な DOCX でコメント、ハイパーリンク、フィールド、アクセシビリティ用メタデータが保持されているとは限りません。主なレビューに使用したビューアーと、確認に使用した別のビューアーを記録してください。

ナビゲーション

リソース

• references/docx-patterns.md - python-docx の注意点：スタイル、表、セクション、フィールド、ハイパーリンク、破損につながる落とし穴
• references/template-workflows.md - docxtpl のタグ配置、フェイルクローズレンダリング、バッチ処理のルール
• references/review-comments-workflows.md - コメント、レビュー用メモ、プログラムによる変更履歴の振り分け、コメントの制限
• references/tracked-changes.md - 変更履歴の記録について、実現可能なこととできないこと
• references/llm-extraction-workflows.md - Mammoth、MarkItDown、Docling、HTML／Markdown／JSON の抽出。ジョブごとのツール候補（ネイティブ解析、構造化変換、OCR）をまとめた Extraction Stack を含みます
• references/docx-extraction-failure-modes.md - KB／RAG への取り込みで発生するサイレントな欠落（コンテンツコントロールの表、画像の表、変更履歴、実態と異なるファイル名）と、表の数を検出するチェック
• references/accessibility-compliance.md - Word のアクセシビリティ、EN 301 549 の概要、手動チェック
• references/cross-platform-compatibility.md - Word、Google Docs、LibreOffice、PDF 変換
• references/document-automation-pipelines.md - CI/CD、バッチ生成、品質ゲート
• data/sources.json - 外部ドキュメントへのリンク

スクリプト

• scripts/docx_inspect_ooxml.py - 依存関係なしで、変更履歴とコメントを OOXML 形式で検査します
• scripts/docx_extract.py - テキスト、表、メタデータと、オプションでヘッダー／フッター／ハイパーリンク／コメント／画像を JSON に抽出します
• scripts/docx_render_template.py - JSON から docxtpl テンプレートをレンダリングし、変数が不足している場合は失敗します（下書きでは --allow-missing を指定）
• scripts/docx_to_html.mjs - 信頼できる .docx を、スタイルマップとオプションの画像抽出を使って HTML に変換します
• scripts/docx_quality_gate.py - 解析可能性、未解決のテンプレートタグ、変更履歴／コメントの兆候、オプションの LibreOffice 変換を検証します。問題がある場合は終了コード 2 を返します

テンプレート

• assets/docx-template-authoring-checklist.md - テンプレートの作成と引き継ぎのチェックリスト

関連スキル

• ../document-pdf/SKILL.md - PDF の生成とリリースのワークフロー
• ../document-xlsx/SKILL.md - スプレッドシートの生成とエクスポート
• ../document-pptx/SKILL.md - プレゼンテーションの生成
• ../docs-codebase/SKILL.md - テクニカルライティングのパターン

学びのループ

過去の判断や落とし穴が関連する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または利用可能な代替ファイルとしてのみ、learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後、記憶に残す価値のあるパターン、再発防止に役立つ間違い、または意外だった分野の事実に気づいた場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付入りの箇条書きを learnings.md に追記してください。SKILL.md 自体は変更しないでください。