formaldoc

formaldoc スキル

公開されている formaldoc npm パッケージを使用して、Markdown を .docx に変換します。

使用するタイミング

Markdown やプレーンテキストだけでなく、実際の Word ドキュメントを出力したい場合に、このスキルを使用します。

よくある依頼：

• 「docx を生成して」
• 「これを Word にエクスポートして」
• 「この Markdown をドキュメントに変換して」
• 「これを .docx として保存して」
• 「Word ファイルをダウンロードして」

ワークフロー

1. テンプレートを決める

ユーザーがすでにテンプレートを選んでいる場合や、文脈から明らかな場合は、そのテンプレートをそのまま使用します。

テンプレートが不明な場合は、簡潔に一度だけ尋ねます。

デフォルトの目安：

• 中国語のビジネス文書または業務報告には cn-report
• 中国語の公的文書または政府文書には cn-gov
• 英語のビジネス文書には en-business
• フォールバックのデフォルト：cn-gov

短い質問の例：

どのテンプレートを使用しますか？デフォルトは cn-report です。利用可能なオプション：cn-gov / cn-general / cn-academic / cn-report / en-standard / en-business / en-academic / en-legal

2. まず Markdown をファイルに書き込み、そのファイルから変換する

重要：必ず最初にコンテンツを .md ファイルに書き込み、そのファイルから変換してください。 これは強く推奨される方法です。理由は次のとおりです。

• ドキュメント全体をコード内の文字列リテラルとして埋め込む必要がなくなり、トークンを節約できます
• Markdown がすでにファイルとして存在する場合は、書き込みを省略してファイルを指定するだけで済みます
• ファイルは、ユーザーが後から確認、編集、再変換できる成果物になります

判断フロー：

Does a .md file already exist on disk?
  ├── YES → use it directly (Step 3a)
  └── NO → write the content to a .md file first, then use it (Step 3a)

メモリ内変換（ステップ 3b）は、一時ファイルへの書き込みが本当に実行不可能な場合（例：ファイルシステムにアクセスできないサンドボックス環境）にのみ使用してください。

3a. ファイルベースの変換（推奨）

CLI を使用してください。最も簡単で、トークン効率のよい方法です。

npx formaldoc input.md -t cn-report -o output.docx

ドキュメントが # ではなく ## から始まる場合は、-l を使用してタイトルの見出しレベルを設定します。

npx formaldoc input.md -t cn-report -l 2 -o output.docx

プログラムから制御する必要がある場合は、Node API を使用することもできます。

import { convertMarkdownToDocxFile } from 'formaldoc';

const result = await convertMarkdownToDocxFile({
  inputPath: '/absolute/path/to/input.md',
  outputPath: '/absolute/path/to/output.docx',
  templateName: 'cn-report',
  titleLevel: 1, // 1-5: which heading level maps to Title (default: 1)
});

console.log(result.outputPath);

3b. メモリ内変換（最終手段）

ファイルシステムが利用できない場合にのみ使用してください。ファイルに書き込める場合は、この方法を使用しないでください。大きな Markdown 文字列をコード内に埋め込むと、多くのトークンを無駄に消費します。

import { writeFile } from 'node:fs/promises';
import { convertMarkdownToDocx } from 'formaldoc';

const result = await convertMarkdownToDocx({
  markdown: '## Title\n\nShort content only.',
  templateName: 'cn-report',
  titleLevel: 2, // ## maps to Title, ### to Heading1, etc.
});

await writeFile('/absolute/path/to/output.docx', result.buffer);

4. 生成したファイルを返す

環境がファイルの返却に対応している場合は、最終出力として .docx ファイルそのものを返してください。

重要な注意事項

• 必ずファイルを先に作成します。 コンテンツが .md ファイルとして存在する場合は、そのファイルから変換します。存在しない場合は、まず .md ファイルに書き込んでから変換します。インラインの Markdown 文字列を使ったメモリ内変換は、大きなドキュメントではトークンを無駄に消費するため、最終手段です。
• formaldoc は ESM を優先します。require() ではなく import を使用してください。
• エージェント環境では、絶対パスを優先してください。
• 実用上可能であれば、ドキュメントのタイトルに合った出力ファイル名を選んでください。
• パスや成功メッセージだけでなく、実際の .docx 成果物を返してください。
• Markdown が # ではなく ## 以下から始まる場合は、titleLevel（API）または -l（CLI）を使用してください。たとえば、titleLevel: 2 を指定すると、## は Title に、### は Heading1 に対応します。有効な範囲：1～5。

テンプレート早見表

文脈	推奨テンプレート
中国語の業務報告、進捗報告、分析	cn-report
中国語の政府、公的機関、または公式文書	cn-gov
一般的な中国語の文書	cn-general
中国語の学術コンテンツ	cn-academic
英語のビジネス文書	en-business
英語の学術コンテンツ	en-academic
英語の法律文書	en-legal
一般的な英語の文書	en-standard