Official MCP + Copilot AI Skills exist, but no official portable Agent Skill (SKILL.md) found

[gryphon2411]

Reporting an observation after looking for an official Mermaid skill on skills.sh:

What I found:

• Official MCP Server exists and is documented at https://mermaid.ai/docs/ai/mcp-server - https://mcp.mermaid.ai/mcp / /sse with tools like validate_and_render_mermaid_diagram
• Official Claude connector exists: Mermaid Chart Connector in Claude's directory
• Official feature called "Mermaid AI Skills for GitHub Copilot" exists in Mermaid-Chart/vscode-mermaid-chart (marketplace command MermaidChart: Install AI Skills for GitHub Copilot / setting mermaidChart.aiSkills.enabled). It installs .github/instructions/mermaid.instructions.md and .github/copilot-instructions.md

What I did NOT find:

• An official portable Agent Skill in SKILL.md format (e.g. .github/skills/mermaid/SKILL.md, .claude/skills/mermaid/SKILL.md) in either mermaid-js or Mermaid-Chart orgs
• No first-party result for https://www.skills.sh/?q=mermaid - only community skills like softaworks/agent-toolkit/mermaid-diagrams

For reference:
jgraph/drawio-mcp ships both an official MCP at mcp.draw.io and an official Claude Code plugin / skill (/plugin install drawio@drawio). Mermaid currently has the first part but not the second.

Not sure if this gap is intentional (MCP + Copilot instructions covering the need) or if a portable skill is planned. Just reporting it in case it's useful.

Repo searched: mermaid-js/mermaid, Mermaid-Chart/vscode-mermaid-chart, skills.sh, claude.com/connectors, npm @mermaid-js.

Cross-posted: I reported this where the Copilot AI Skills live: Mermaid-Chart/vscode-mermaid-chart#151 - reposting here for visibility in the OSS org.

[Hahaknight]

Confirming the gap is real, and adding context on why it exists + what filling it would get you.

The portable SKILL.md format is much newer than MCP — the ecosystem only coalesced around it this year via the open skills installer (npx skills add owner/repo), which now installs into Claude Code, Codex, Cursor, Gemini CLI, Goose, Crush, Qwen Code and 78+ agents total. That's the real difference vs the Copilot-specific instructions file you found: one SKILL.md, every agent. drawio shipping both is the right model.

For whoever writes it (maintainer or community), two things that decide whether a skill actually gets used:

1. The description frontmatter is the trigger surface, not documentation. Agents never load the body until the description matches the task — vague descriptions ("helps with diagrams") sleep forever; precise ones ("MUST USE when the user asks to render/validate a mermaid diagram or fix mermaid syntax errors") fire every time.
2. Ground the body against source, not memory — exact directive names, real parser error strings, version-boundary syntax. That's what stops the skill itself from hallucinating.

Full write-up of both points (description formula + pre-release checks): https://hahaknight.github.io/claude-skills-pro/how-to-write-skills-en.html — working reference implementation of the cross-agent install path: https://github.com/Hahaknight/claude-skills-pro (15 engineering-workflow skills, 7 free/MIT).

One design note: since Mermaid already ships the MCP for render/validate, the SKILL.md's job is complementary — syntax-repair workflow, version-compat gotchas, diagram-type selection. MCP = capability, Skill = method. That's how the two formats compose.