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

[furukawa658]

Summary

Add markdown-to-word-mermaid, a self-contained skill for converting Markdown documents containing Mermaid code fences to DOCX. The bundled Python converter renders diagrams locally with Mermaid CLI, embeds vector SVGs using Office OOXML relationships, and retains 3x PNG fallbacks. Diagram paragraphs keep their aspect ratio, remain together, and use page-aware scaling and page breaks.

This complements the existing general md-to-docx workflow by focusing on Mermaid rendering, SVG packaging, Office-compatible labels, and tall-diagram placement. It does not create individually editable Word shapes, connectors, or diagram text.

Contents

• English SKILL.md with prerequisites, safe output handling, workflow, limitations, and verification commands.
• Python converter and bounded dependency requirements; no vendored libraries, browsers, fonts, or generated documents.
• Synthetic English/Japanese sample with three diagrams, including a tall flowchart.
• Mocked converter tests, an opt-in real-renderer integration test, and overwrite-preservation coverage.
• Maintainer publication notes and the generated docs/README.skills.md entry.

Verification

• npm run skill:validate: passed for all 430 skills, including this candidate.
• npm run build: passed and generated the new skill listing.
• Converter and overwrite regressions: passed in the submitted working tree. The optional real-renderer test was skipped in that final regression invocation.
• Separate real Mermaid rendering and independent-context execution produced all three SVGs and PNG fallbacks. Image relationships, package integrity, English/Japanese labels, and source/output preservation were checked.
• Word 16.0 opened the sample read-only and exported three PDF pages; all exported pages were visually inspected. The original DOCX was unchanged.
• An independent context verified normal conversion, refusing an existing destination, rejecting invalid Mermaid without changing the source, and explaining the native-editable-shape boundary.

Limitations and Disclosure

SVG rendering requires an SVG-capable Word viewer and an installed font; fonts are not embedded. Ordinary Markdown image links are represented as text rather than embedded images. The title/frontmatter handling is intentionally limited, not a full YAML metadata parser. Word GUI zoom, physical printing, automatic skill selection, and non-Windows execution were not verified.

The tall sample remains on its own page, but its heading stays on the preceding page; branch labels may have connectors visible behind them. One independent execution timed out at a 170-second test cap; a sequential recheck with a 300-second cap completed in about 100 seconds. The earlier timeout cause is unverified, and no performance or skill-quality uplift is claimed.

The rights holder confirmed ownership/authority and authorized offering the skill's own code, documentation, and synthetic sample under MIT. Runtime dependencies retain their respective licenses and are not redistributed with the skill.

AI-assisted contribution. Local checks are not hosted CI results or maintainer approval.

[github-actions]

🔒 PR Risk Scan Results

Scanned 6 changed file(s).

Severity	Count
🔴 High	0
🟠 Medium	0
ℹ️ Info	2

Severity	Rule	File	Line	Match
ℹ️	skill-script-touched	skills/markdown-to-word-mermaid/scripts/markdown_to_word.py	1	skills/markdown-to-word-mermaid/scripts/markdown_to_word.py
ℹ️	skill-script-touched	skills/markdown-to-word-mermaid/tests/test_markdown_to_word.py	1	skills/markdown-to-word-mermaid/tests/test_markdown_to_word.py

This is an automated soft-gate report. Findings indicate review targets and do not block merge by themselves.

[github-actions]

🚦 Submission status: 👀 Ready for review

Risk tier: merge-risk:high — Privileged execution, automation, or review-policy change
Required to merge: passing submission-gate checks plus 1 approval from reviewers with write access, including a maintainer with admin or maintain permission.

Why this tier

• skills/markdown-to-word-mermaid/scripts/markdown_to_word.py is a high-risk path (automation, scripts, MCP config, hooks, or review policy)
• skills/markdown-to-word-mermaid/scripts/requirements.txt is a high-risk path (automation, scripts, MCP config, hooks, or review policy)
• skills/markdown-to-word-mermaid/tests/test_markdown_to_word.py is a high-risk path (automation, scripts, MCP config, hooks, or review policy)

Automated checks

Check	Status	Details
Line endings	✅ Passed	Passed · logs
Spelling	✅ Passed	Passed · logs
Generated README consistency	✅ Passed	Passed · logs
Skill validation	✅ Passed	Passed · logs
Skill lint (vally)	✅ Passed	Passed · logs
Risk scan	✅ Passed	Passed · logs
Contributor reputation	✅ Passed	Passed · logs
Duplicate resource scan	✅ Passed	Passed · logs
PR quality signal	⏭️ Skipped	Skipped by its workflow · logs

Review

• Approvals: 0/1
• Assigned reviewer: not assigned yet — comment /request-review to ask for one
• Review target date: not set
• Still needed: 1 more approval(s); an approval from a maintainer with admin or maintain permission
• The core-maintainers pool is not staffed yet; an approver with admin or maintain permission is required instead.

Commands

Command	Who	What it does
/rerun-checks	PR author, maintainers	Re-runs failed or incomplete checks and re-evaluates this gate
/request-review	PR author, maintainers	Asks the review rotation to assign a reviewer (adds needs-reviewer)

_{Updated for c98fef0 · gate run · This comment is maintained automatically — see submission gate docs.}

[github-actions]

🔍 Vally Lint Results

✅ All checks passed

Scope	Checked
Skills	1
Agents	0
Total	1

Severity	Count
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	✅ markdown-to-word-mermaid (2/2 checks passed)
ℹ️	✓ [spec-compliance] All 1 skill(s) are spec-compliant.
ℹ️	✓ spec-compliance: All spec checks passed.
ℹ️	✓ [valid-refs] All file references across 1 skill(s) are valid.
ℹ️	✓ valid-refs: All file references resolve to existing files within the skill directory.
ℹ️	1 skill(s) linted, 1 passed

Full linter output

### Linting skills/markdown-to-word-mermaid
✅ markdown-to-word-mermaid (2/2 checks passed)
    ✓ [spec-compliance] All 1 skill(s) are spec-compliant.
        ✓ spec-compliance: All spec checks passed.
    ✓ [valid-refs] All file references across 1 skill(s) are valid.
        ✓ valid-refs: All file references resolve to existing files within the skill directory.

1 skill(s) linted, 1 passed

[Copilot]

🟡 Changes recommended

Output-safety, ordered-list correctness, accessibility, and stale generated-asset issues remain unresolved.

4 open findings

• Preserve ordered-list starts and numbering context · New
• Publish DOCX only after successful injection · New
• Exclude pycache files from generated asset listings · New
• Add meaningful alternative descriptions to diagrams · New

What changed in this PR

Adds a differentiated Mermaid-focused Markdown-to-DOCX skill with vector SVG packaging, PNG fallbacks, and page-aware layout. Knowledge uplift is high due to the bundled converter and OOXML handling.

Changes:

• Adds the converter, dependency bounds, and usage guidance.
• Adds mocked and optional real-renderer tests plus a multilingual sample.
• Adds publication notes and generated skill documentation.

File	Description
skills/​markdown-to-word-mermaid/​SKILL.md	Defines setup, workflow, limitations, and verification.
skills/​markdown-to-word-mermaid/​scripts/​markdown_to_word.py	Implements conversion, rendering, layout, and SVG packaging.
skills/​markdown-to-word-mermaid/​scripts/​requirements.txt	Declares bounded Python dependencies.
skills/​markdown-to-word-mermaid/​tests/​test_markdown_to_word.py	Tests rendering and DOCX packaging.
skills/​markdown-to-word-mermaid/​scripts/​tests/​test_markdown_to_word.py	Tests overwrite preservation.
skills/​markdown-to-word-mermaid/​assets/​example.md	Provides multilingual sample content.
skills/​markdown-to-word-mermaid/​references/​publication.md	Records publication and validation notes.
docs/​README.skills.md	Registers the skill in generated documentation.

🧠 Review effort: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

Output staging can overwrite or leave incomplete files, and renderer execution is unbounded.

3 open findings

• Publish DOCX only after successful injection
• Preserve ordered-list starts and numbering context
• Add meaningful alternative descriptions to diagrams

1 resolved since last review

• Exclude pycache files from generated asset listings

Previously missed (1)

In code that hasn't changed since last review

Add renderer timeout and terminate spawned browser processes

skills/​markdown-to-word-mermaid/​scripts/​markdown_to_word.py:83

This renderer call has no timeout, so a stuck Mermaid CLI or browser can block an agent indefinitely. The PR's own validation reports a 170-second timeout, making this a demonstrated failure mode rather than a hypothetical one. Add a documented configurable timeout and convert TimeoutExpired into a clear rendering error while ensuring spawned browser processes are terminated.

🧠 Review effort: Balanced

[furukawa658]

Addressed all four Copilot review findings and cleaned up the skill package in 03ab02c:

• Added a per-command timeout (--timeout, default 120 seconds) to subprocess.run when invoking Mermaid CLI and converted subprocess.TimeoutExpired into a descriptive RuntimeError.
• Changed convert_markdown to stage intermediate DOCX outputs inside TemporaryDirectory() and move the final file to output_path only after _inject_svg_parts succeeds, leaving the destination directory untouched on failure.
• Preserved ordered list start numbers and separate ordered list boundaries instead of delegating all numbered items to Word's shared List Number sequence.
• Populated diagram wp:docPr title and descr with contextual alt text derived from Mermaid accTitle/accDescr, the preceding heading, and the diagram type.
• Replaced internal Japanese notes in references/publication.md with English scope and evaluation documentation, and consolidated the duplicate scripts/tests/test_markdown_to_word.py into tests/test_markdown_to_word.py.

Validation: 8 unit tests (including real Mermaid CLI rendering) pass, npm run skill:validate and npm run build pass with zero drift.

/request-review

[Copilot]

🟡 Changes recommended

Output publication can overwrite concurrent results or leave partial files, and list continuation paragraphs receive incorrect markers.

3 open findings

• Preserve list-item boundaries across continuation paragraphs · New
• Stage temporary DOCX files on the destination filesystem · New
• Atomically publish documents without overwriting existing destinations · New

3 resolved since last review

• Publish DOCX only after successful injection
• Preserve ordered-list starts and numbering context
• Add meaningful alternative descriptions to diagrams

🧠 Review effort: Balanced

[furukawa658]

Addressed the 3 follow-up review comments in 28495d7:

• Track list_item_open and list_item_close boundaries so continuation paragraphs within ordered and unordered list items use List Continue without emitting duplicate numbers or bullets.
• Stage the temporary directory under output_path.parent so final publication stays on the destination filesystem.
• Publish the completed DOCX atomically without overwriting existing files via os.link (with O_CREAT | O_EXCL fallback).

/request-review

[Copilot]

🟡 Changes recommended

Windows command injection, non-atomic fallback publication, and content-preservation defects remain unresolved.

2 open findings

• Shell injection and conversion failure via unescaped Windows paths · New
• Fallback publication exposes incomplete destination files · New

3 resolved since last review

• Atomically publish documents without overwriting existing destinations
• Stage temporary DOCX files on the destination filesystem
• Preserve list-item boundaries across continuation paragraphs

Previously missed (2)

In code that hasn't changed since last review

Quoted paragraphs lose list markers and numbering

skills/​markdown-to-word-mermaid/​scripts/​markdown_to_word.py:192

Returning immediately for quote_depth bypasses list formatting. For example, > 5. First followed by > 6. Second becomes two Quote paragraphs containing only First and Second, losing the list markers and starting number. Handle list_stack for quoted paragraphs as well, preserving list markers and continuation state while applying quote formatting.

Leading thematic break incorrectly strips non-frontmatter content

skills/​markdown-to-word-mermaid/​scripts/​markdown_to_word.py:523

A leading thematic break is treated as frontmatter whenever another --- occurs later, without checking whether the enclosed text is metadata. A document beginning with ---, a heading and Mermaid fence, then another --- silently loses the heading and diagram here. Validate the supported metadata structure before removing this region, and preserve the original Markdown when it does not match.

🧠 Review effort: Balanced

[furukawa658]

Addressed both new review findings in c98fef0:

• Resolve Windows .cmd/.bat shims to the Mermaid JavaScript entry point and invoke it through Node with an argument list and no shell, avoiding cmd.exe metacharacter interpretation in paths such as R&D.
• Keep publication atomic: use hard-link creation where available, use Windows atomic no-replace rename when hard links are unavailable, and fail clearly on other systems instead of creating a visible partial destination.
• Added Windows path and publication fallback regression coverage.

/request-review

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.