Add Mermaid-to-Word SVG export skill 🤖🤖🤖

docs/README.skills.md

@@ -266,6 +266,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
 | [make-blog-post](../skills/make-blog-post/SKILL.md)<br />`gh skills install github/awesome-copilot make-blog-post` | Turn code from the current session into a blog post written in the voice of its author. Covers one function, script, class, or tool as a focused walkthrough with a generalized sample and a usage example, learns tone and structure from existing posts or writing samples by the same author, takes the destination from what the user names or the blog repository in use instead of assumed folders, and saves no file until the draft is approved. Use when asked to write, draft, or turn code into a blog post, article, tutorial, or gist, or when invoked as /make-blog-post at the end of a turn. | `assets/voice-profile-template.md`<br />`references/blog-platforms.md`<br />`references/delivery.md`<br />`references/seo.md`<br />`references/voice-profile.md` |
 | [make-repo-contribution](../skills/make-repo-contribution/SKILL.md)<br />`gh skills install github/awesome-copilot make-repo-contribution` | All changes to code must follow the guidance documented in the repository. Before any issue is filed, branch is made, commits generated, or pull request (or PR) created, a search must be done to ensure the right steps are followed. Whenever asked to create an issue, commit messages, to push code, or create a PR, use this skill so everything is done correctly. | `assets/issue-template.md`<br />`assets/pr-template.md` |
 | [markdown-to-html](../skills/markdown-to-html/SKILL.md)<br />`gh skills install github/awesome-copilot markdown-to-html` | Convert Markdown files to HTML similar to `marked.js`, `pandoc`, `gomarkdown/markdown`, or similar tools; or writing custom script to convert markdown to html and/or working on web template systems like `jekyll/jekyll`, `gohugoio/hugo`, or similar web templating systems that utilize markdown documents, converting them to html. Use when asked to "convert markdown to html", "transform md to html", "render markdown", "generate html from markdown", or when working with .md files and/or web a templating system that converts markdown to HTML output. Supports CLI and Node.js workflows with GFM, CommonMark, and standard Markdown flavors. | `references/basic-markdown-to-html.md`<br />`references/basic-markdown.md`<br />`references/code-blocks-to-html.md`<br />`references/code-blocks.md`<br />`references/collapsed-sections-to-html.md`<br />`references/collapsed-sections.md`<br />`references/gomarkdown.md`<br />`references/hugo.md`<br />`references/jekyll.md`<br />`references/marked.md`<br />`references/pandoc.md`<br />`references/tables-to-html.md`<br />`references/tables.md`<br />`references/writing-mathematical-expressions-to-html.md`<br />`references/writing-mathematical-expressions.md` |
+| [markdown-to-word-mermaid](../skills/markdown-to-word-mermaid/SKILL.md)<br />`gh skills install github/awesome-copilot markdown-to-word-mermaid` | Export Markdown containing Mermaid code fences to Word (.docx) with embedded SVG diagrams and PNG fallbacks. Use when diagram sharpness, Office-compatible labels, or page-aware placement matters. Not for Word-to-Markdown conversion, editable Office shapes, or general slide creation. | `assets/example.md`<br />`references/publication.md`<br />`scripts/markdown_to_word.py`<br />`scripts/requirements.txt`<br />`scripts/tests/test_markdown_to_word.py`<br />`tests/test_markdown_to_word.py` |
 | [markstream-install](../skills/markstream-install/SKILL.md)<br />`gh skills install github/awesome-copilot markstream-install` | Install and configure Markstream streaming Markdown renderers for Vue, React, Svelte, Angular, Nuxt, and Vue 2 applications. Use for package selection, minimal peer dependencies, CSS order, SSR boundaries, streaming mode, and renderer setup. | `references/scenarios.md` |
 | [mcp-cli](../skills/mcp-cli/SKILL.md)<br />`gh skills install github/awesome-copilot mcp-cli` | Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers, list available MCP servers/tools, or call MCP tools from command line. | None |
 | [mcp-copilot-studio-server-generator](../skills/mcp-copilot-studio-server-generator/SKILL.md)<br />`gh skills install github/awesome-copilot mcp-copilot-studio-server-generator` | Generate a complete MCP server implementation optimized for Copilot Studio integration with proper schema constraints and streamable HTTP support | None |

skills/markdown-to-word-mermaid/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: markdown-to-word-mermaid
+description: 'Export Markdown containing Mermaid code fences to Word (.docx) with embedded SVG diagrams and PNG fallbacks. Use when diagram sharpness, Office-compatible labels, or page-aware placement matters. Not for Word-to-Markdown conversion, editable Office shapes, or general slide creation.'
+license: MIT
+argument-hint: 'Markdown input file and optional DOCX output path'
+user-invocable: true
+---
+
+# Markdown to Word with Mermaid
+
+Export technical documents without manually replacing Mermaid fences with screenshots. The bundled converter renders each diagram locally, embeds the SVG through Office OOXML relationships, and retains a 3x PNG fallback. Word is not required to generate the file; an SVG-capable Word version is needed to inspect vector rendering.
+
+## When to use
+
+- A design document, runbook, or report contains Mermaid code fences and must be delivered as DOCX.
+- Diagram labels must remain sharp when zoomed or printed.
+- A tall diagram needs page-aware placement rather than being split across pages.
+
+For general Markdown-to-DOCX conversion with existing PNG images, a general converter such as `md-to-docx` may be simpler. This skill focuses on rendering and packaging Mermaid diagrams. SVG embedding does not create editable Word shapes, connectors, or text boxes.
+
+## Requirements and setup
+
+- Python 3.10+ and the packages in [scripts/requirements.txt](scripts/requirements.txt).
+- Node.js compatible with the chosen Mermaid CLI release, plus `@mermaid-js/mermaid-cli`.
+- A local browser usable by Puppeteer and an installed font covering the document's characters.
+- Default font: Noto Sans JP. Use `--font-family` to select another installed family.
+
+Resolve paths relative to this skill's installation directory, not an assumed repository name. The examples below run from the skill directory. Use the user's selected Python environment (`python`, `python3`, or its absolute path).
+
+Before installing dependencies, confirm the environment and obtain permission if required. Reuse an existing Mermaid CLI when available. Otherwise install it into a user-approved local tools directory, not globally:
+
+```sh
+python -m pip install -r scripts/requirements.txt
+npm install --prefix ./run/mermaid-cli @mermaid-js/mermaid-cli
+```
+
+The local executable is `./run/mermaid-cli/node_modules/.bin/mmdc` on POSIX and `./run/mermaid-cli/node_modules/.bin/mmdc.cmd` on Windows. Keep installed dependencies out of the submitted skill package. Lock the selected dependency versions in the consuming project for reproducible installations.
+
+On Windows the converter detects standard Chrome and Edge paths. For another browser location, set `MERMAID_BROWSER_PATH` to its absolute executable path:
+
+```powershell
+$env:MERMAID_BROWSER_PATH = "C:\Program Files\Google\Chrome\Application\chrome.exe"
+```
+
+On POSIX, use `export MERMAID_BROWSER_PATH=/absolute/path/to/browser`, or use Puppeteer's installed browser. Do not disable the browser sandbox just to make a conversion pass.
+
+## Workflow
+
+1. Confirm the input Markdown file, output destination, and font. If no destination is provided, use the input path with a `.docx` extension.
+2. Check that the output does not exist. Never delete or overwrite an existing document; ask for a different destination.
+3. Run [scripts/markdown_to_word.py](scripts/markdown_to_word.py). Preserve the user's diagram source and meaning. Do not silently repair invalid Mermaid.
+4. Check the generated package and, when Word is available, inspect the document visually. Report package checks and visual checks separately.
+
+With `mmdc` on PATH:
+
+```sh
+python scripts/markdown_to_word.py input.md --output output.docx
+```
+
+Using a workspace-local CLI on Windows:
+
+```powershell
+python scripts/markdown_to_word.py input.md --output output.docx --mermaid-cli ./run/mermaid-cli/node_modules/.bin/mmdc.cmd
+```
+
+Selecting an installed font:
+
+```sh
+python scripts/markdown_to_word.py input.md --output output.docx --font-family "Noto Sans JP"
+```
+
+For a reproducible example, convert [assets/example.md](assets/example.md) to a new output path. It includes English and Japanese labels, multiple diagrams, and a tall diagram.
+
+## Conversion behavior
+
+- Headings, paragraphs, emphasis, lists, blockquotes, tables, and code blocks become Word content.
+- Each Mermaid fence renders to SVG and a 3x PNG. Office SVG extensions reference the SVG; the normal image reference retains the PNG fallback.
+- The selected font is applied to Word paragraph styles and Mermaid's font configuration. Code runs use Consolas. Fonts are not embedded; unavailable fonts may be substituted.
+- `htmlLabels: false` is set globally and for flowcharts to avoid HTML `foreignObject` labels that Office may not display. Check actual SVG output for unsupported constructs.
+- Diagrams are centered, keep their aspect ratio, and use a non-splitting paragraph. Diagrams occupying at least 70% of the page body height start on a new page. Oversized diagrams are scaled to the page body height. Large diagrams generate a readability warning.
+- A simple single-line frontmatter `title` becomes the document title; other frontmatter fields are removed from the body. This is not a full YAML metadata parser.
+- Ordinary Markdown image links remain alt text and a source path or URL; they are not embedded. Raw HTML is reduced to text, not executed.
+
+## Stop conditions and limitations
+
+- Missing input, wrong extensions, an existing output, missing CLI, invalid Mermaid, rendering failure, or unusable SVG dimensions stop the conversion with an error.
+- The converter does not call an external rendering service or a separate AI API. Dependency installation and browser execution are not an offline sandbox. Review untrusted diagram content, including external resources, before rendering it.
+- Diagrams are not semantically editable Office objects. Word rendering, font substitution, and final pagination depend on the viewer and must be checked there.
+- A successfully created DOCX is not proof that every diagram label is readable. Split large diagrams in the source only with the user's approval.
+
+## Verification
+
+Run both existing test suites from the skill directory:
+
+```sh
+python -m unittest discover -s tests -v
+python -m unittest discover -s scripts/tests -v
+```
+
+The ordinary suite mocks Mermaid rendering. To run the real-renderer test as well, set `MERMAID_CLI` to the CLI executable's absolute path, then run the first command again. On Windows PowerShell:
+
+```powershell
+$env:MERMAID_CLI = (Join-Path $env:APPDATA "npm\mmdc.cmd")
+python -m unittest discover -s tests -v
+```
+
+That test renders the bundled sample and checks the resulting DOCX's SVG references, PNG fallbacks, labels, and drawing dimensions. It does not automate Word visual inspection.
+
+Before reporting completion:
+
+- Count Mermaid fences and verify the same number of SVG parts and SVG image references in the DOCX.
+- Confirm PNG fallback references exist and no label `foreignObject` remains in the sample's SVGs.
+- In Word, inspect node names, branch labels, font, diagram placement, and page boundaries; check zoomed or printed output when sharpness matters.
+- If Word or the actual renderer was unavailable, state which checks were not performed.
+
+For contribution scope, evaluation cases, and a draft submission description, see [references/publication.md](references/publication.md). That file is maintainer guidance, not permission to publish.
+
+## Gotchas
+
+- `mmdc.cmd` needs Windows command handling; pass its path with `--mermaid-cli` rather than rewriting the script.
+- A missing font can affect both PNG rendering and SVG display. Use a family installed on the rendering and viewing machines.
+- Keep the SVG and PNG paired. Replacing SVG with a screenshot defeats the vector-preserving workflow.
+- Package validation, renderer tests, agent-selection evaluation, and human visual acceptance are different checks.

skills/markdown-to-word-mermaid/assets/example.md

@@ -0,0 +1,56 @@
+---
+title: Mermaid delivery sample
+---
+
+This synthetic example contains no project or customer data.
+
+## Approval flow
+
+The document owner submits a draft. A reviewer either approves it or requests changes.
+
+```mermaid
+flowchart LR
+    Draft[Draft] --> Review{Approved?}
+    Review -->|Yes| Publish[Publish]
+    Review -->|No| Revise[Revise]
+    Revise --> Draft
+```
+
+## Japanese labels
+
+```mermaid
+flowchart LR
+    Input[入力] --> Check{確認済み?}
+    Check -->|はい| Output[出力]
+    Check -->|いいえ| Return[差戻し]
+```
+
+## Tall diagram
+
+This diagram exercises scaling and the explicit page-break rule.
+
+```mermaid
+flowchart TD
+    Receive[Receive request] --> Validate[Validate input]
+    Validate --> Read[Read Markdown]
+    Read --> Parse[Parse blocks]
+    Parse --> Render[Render SVG]
+    Render --> Fallback[Render PNG fallback]
+    Fallback --> Package[Package document]
+    Package --> Inspect[Inspect package]
+    Inspect --> Preview[Preview in Word]
+    Preview --> Deliver[Deliver document]
+```
+
+## Ordinary content
+
+| Item | Expected result |
+| ---- | --------------- |
+| SVG  | SVG retained    |
+| PNG  | PNG retained    |
+| Text | Both languages  |
+
+- Keep the Markdown source.
+- Check the document in Word.
+
+> Vector output is not an editable Office flowchart.

skills/markdown-to-word-mermaid/references/publication.md

@@ -0,0 +1,63 @@
+# Awesome Copilot 公開準備
+
+## 提案内容
+
+このスキルは、Mermaidコードフェンスを含むMarkdown文書をDOCXへ変換する。Mermaid CLIでSVGを描画し、Word文書にSVGとPNGフォールバックを格納する。SVGのOffice OOXML関連付け、HTMLラベルによる文字欠落の回避、縦長図の改ページと縮小を扱う。
+
+既存の `md-to-docx` は、Markdown本文と既存PNG画像をWordへ変換する汎用用途を扱う。本スキルはMermaidソースからの描画、ベクターSVGの格納、図のページ配置に焦点を絞る。SVGの埋め込みは、Word上で図形・線・文字を個別編集できることを意味しない。
+
+## 投稿案
+
+Title:
+
+```text
+Add Mermaid-to-Word SVG export skill
+```
+
+Description:
+
+```text
+Export Markdown documents with Mermaid diagrams to Word, preserving vector SVGs with PNG fallbacks and page-aware placement.
+```
+
+Summary:
+
+```text
+This skill converts Markdown documents containing Mermaid code fences into Word documents. It renders diagrams locally with Mermaid CLI, embeds SVG through Office OOXML relationships, retains PNG fallbacks, and keeps large diagrams together with page-aware placement. It is intended for technical documents that need readable diagrams in DOCX, not general Markdown conversion or editable Office shapes.
+```
+
+## 評価ケース
+
+| 入力・依頼 | 期待結果 |
+| --- | --- |
+| Mermaidフロー図を含む設計書をWordへ出力 | 本スキルを選び、DOCXにSVGとPNGを格納する |
+| 縦長のMermaid図を含む手順書をWordへ出力 | 図を段落間で分割せず、必要に応じて改ページ・縮小する |
+| PNG画像だけを含む一般的なMarkdownをWordへ変換 | Mermaid固有の機能が不要なら汎用変換スキルを候補にする |
+| Word上でMermaid図の各図形やラベルを編集したい | 本スキルは図形編集を保証しないと説明し、適合する別手段を案内する |
+| Mermaid CLIまたは描画に必要なブラウザーがない | 前提条件を示し、描画またはインストール前に停止する |
+
+## 投稿前の確認
+
+- Awesome Copilotの現行投稿手順に沿い、skill作成・検証コマンドを投稿先リポジトリ上で実行する。
+- 匿名サンプルを含め、公開物に顧客情報、社内パス、認証情報がないことを確認する。
+- 依存パッケージのライセンスと同梱コードの権利を確認する。
+- 投稿先の貢献規約により変更はMITライセンスで提供されるため、権利者が同条件での提供を承認できることを確認する。
+- 実描画テスト、DOCX内のSVG・PNG・ラベル検査、Wordでの目視確認を別々に記録する。自動テストの合格をWord表示の受入に読み替えない。
+- 投稿先リポジトリでskillの作成・検証を行い、生成READMEを更新してからPRを作成する。公開操作は別途承認を得て行う。
+
+## 現在の確認状況
+
+- `assets/example.md` は架空の英語・日本語ラベルを使い、承認フロー、縦長図、通常のMarkdown表を含む。
+- Mermaid CLIを模擬する5件、サンプルを実描画する1件、既存DOCXの上書き防止を確認する1件の計7件が合格した。実描画では3図のSVG参照、PNG格納、英語・日本語ラベル、図の寸法を検査した。
+- Word 16.0でDOCXを読み取り専用で開き、PDFの全3ページを画像で目視確認した。英日ラベル、分岐線、図全体の収まりを確認し、元DOCXのハッシュは不変だった。縦長図は2ページ目に収まるが、見出しは1ページ目に残る。分岐ラベルの背後に接続線が見える箇所もある。Wordの操作画面での拡大確認と実機印刷は未実施である。
+- 別コンテキストの担当が、スキル本文を読まずに行う実行と、本文を読んで行う実行を比較した。本文ありの再実行では正常変換、既存出力への上書き拒否、不正Mermaidでの停止、編集可能なWord図形が対象外であることの説明を確認した。本文なしでも同梱変換器による変換・停止は成功しており、本文ありの変換品質向上は主張しない。自動スキル選択は評価していない。
+- 本文ありの実行は一度170秒でタイムアウトした。300秒上限での再実行は約100秒で完了したが、前回の原因は未確認であり、性能改善とは扱わない。
+- 投稿先 `github/awesome-copilot` のコミット `156736fb63e965b2f547a1460f3b5972c46e6b24` を固定し、候補を含む430スキルの `npm run skill:validate` と `npm run build` が終了コード0で完了した。これはローカルでの公式コマンド実行結果であり、投稿後のCIやメンテナー承認ではない。
+
+## ライセンスと公開権限
+
+2026年10月13日、利用者がスキル自身のコード・文書・サンプルの権利保有と承認権限を確認し、MIT提供を承認した。これは利用者の確認に基づく記録であり、AIが権利関係を法的に確定したものではない。作業領域はGit管理外であり、作者・転載元を履歴から追跡できなかった。
+
+実行環境のライセンス本文とメタデータを確認した。`python-docx`、`markdown-it-py`、`mdurl`、Mermaid CLI、MermaidはMIT、`lxml` はBSD-3-Clause、`typing-extensions` はPSF-2.0である。PuppeteerのパッケージメタデータはApache-2.0だが、今回のインストール先でライセンス本文は確認できなかった。`lxml` の同梱物にも個別条件があるため、ライブラリ全体をMITへ変更できるとは解釈しない。
+
+投稿候補には依存ライブラリ本体、ブラウザー、フォント、DOCX、実行ログを同梱しない。フォントも文書へ埋め込まない。同梱する範囲を将来変える場合は、その範囲の再配布条件を別途確認する。公開、push、PR作成は未実施である。