feat: add mermaid-md skill for rendering mermaid blocks in Markdown

[TheNha]

Pull Request Checklist

• I have read and followed the CONTRIBUTING.md guidelines.
• I have read and followed the Guidance for submissions involving paid services.
• My contribution adds a new instruction, prompt, agent, skill, workflow, or canvas extension file in the correct directory.
• The file follows the required naming convention.
• The content is clearly structured and follows the example format.
• I have tested my instructions, prompt, agent, skill, workflow, or canvas extension with GitHub Copilot.
• I have run npm start and verified that README.md is up to date.
• I am targeting the main branch for this pull request.

---

Description

Adds the mermaid-md skill: it takes a Markdown file that already contains ```mermaid blocks and renders each block to a PNG/SVG/PDF, optionally inserting the image under its block.

This is the opposite direction from authoring a diagram — nothing here writes .mmd files. The Markdown stays the single source of truth, and failures are reported against the block's line range in the .md (docs/design.md:633-654) so the diagram gets fixed where it lives.

Why it's useful: GitHub, GitLab and Obsidian render mermaid natively, but Word, PDF, Confluence, SharePoint and slide decks do not. Today that means hand-exporting each diagram through mermaid.live. The skill turns a 20-diagram RFC into 20 named PNGs in one command, and pairs directly with the existing md-to-docx skill, which embeds PNGs referenced from the Markdown:

python3 skills/mermaid-md/scripts/mermaid_md.py report.md -o assets/ --rewrite report.docx.md
node skills/md-to-docx/scripts/md-to-docx.mjs report.docx.md report.docx

What the bundled script does beyond a mmdc one-liner:

• --list inventories the blocks (index, line range, diagram type, title) before rendering anything
• --check validates every block into a temp dir and exits non-zero — CI-ready
• --only 2,5-7 re-renders just the blocks that changed
• Correct block detection: ``` and ~~~ fences, blocks indented inside list items, while skipping mermaid examples nested in a longer outer fence, other languages, and YAML front matter
• Meaningful filenames (design-03-auth-flow.png) from a %% title: comment, front-matter title:, or the nearest heading; accents folded to ASCII so non-English headings stay readable
• --in-place keeps the mermaid block and puts the image underneath, and is idempotent — re-running refreshes that image line instead of stacking duplicates, so it fits a pre-commit hook
• Resolves its own toolchain: finds a Node >= 18 when an active conda/nvm environment shadows it with an old one (the usual cause of SyntaxError: Unexpected token import from mmdc), finds Chrome in Puppeteer's cache or on the system, and retries with --no-sandbox in containers

Everything renders locally through mermaid-cli — no diagram content is sent to any service.

---

Type of Contribution

• New instruction file.
• New prompt file.
• New agent file.
• New plugin.
• New skill file.
• New agentic workflow.
• New canvas extension.
• Update to existing instruction, prompt, agent, plugin, skill, workflow, or canvas extension.
• Other (please specify):

---

Additional Notes

On the unchecked box: the script itself is tested end-to-end — --list, --check, PNG/SVG/PDF output, --only, both rewrite modes, idempotent --in-place, and the toolchain-recovery paths (old Node on PATH, missing Chrome, bad --chrome) — on Linux with mermaid-cli 11.16, Node 20 and system Chrome, including a 7-diagram Vietnamese design doc. It has been driven by an agent through its SKILL.md, but not specifically through GitHub Copilot, so I have left that box unchecked rather than tick something I did not verify.

npm run skill:validate reports mermaid-md is valid (411 skills pass), and npm run build adds exactly one row to docs/README.skills.md.

Requires python3 (standard library only), Node >= 18, @mermaid-js/mermaid-cli, and a Chrome/Chromium — the same browser dependency mermaid-cli already has.

[github-actions]

🔒 PR Risk Scan Results

Scanned 2 changed file(s).

Severity	Count
🔴 High	0
🟠 Medium	3
ℹ️ Info	1

Severity	Rule	File	Line	Match
🟠	package-exec-command	skills/mermaid-md/SKILL.md	40	npx puppeteer browsers install chrome-headless-shell # skip if a system Chrome exists
ℹ️	skill-script-touched	skills/mermaid-md/scripts/mermaid_md.py	1	skills/mermaid-md/scripts/mermaid_md.py
🟠	package-exec-command	skills/mermaid-md/scripts/mermaid_md.py	301	' npx puppeteer browsers install chrome-headless-shell')
🟠	package-exec-command	skills/mermaid-md/scripts/mermaid_md.py	337	' npx puppeteer browsers install chrome-headless-shell\\n'

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

[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
ℹ️	✅ mermaid-md (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/mermaid-md
✅ mermaid-md (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