markdown-mermaid-writing

Comprehensive markdown and Mermaid diagram writing skill. Use when creating any scientific document, report, analysis, or visualization. Establishes text-based diagrams as the default documentation standard with full style guides (markdown + mermaid), 24 diagram type references, and 9 document templates.

Quality

78%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/markdown-mermaid-writing/SKILL.md

Quality

Content

65%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured, highly actionable guide for Mermaid-in-markdown authoring with strong reference indexing. Its weaknesses are advocacy/philosophy padding and a significant bundle defect: a templates/ directory with 9 referenced templates is missing entirely, breaking two workflow steps and part of the reference index.

Suggestions

Add the missing templates/ directory with the 9 referenced template files (decision_record, how_to_guide, issue, kanban, presentation, project_documentation, pull_request, research_paper, status_report), or remove the Step 1 template table and the templates reference-index entry to stop pointing at non-existent files.

Trim the "Source Format Philosophy" advocacy (the comparison table, "core bet" paragraph, and Discord blockquote) to the essential rule — Mermaid-first, Phase 1 mandatory — to recover token budget.

Add an explicit validation feedback loop to the core workflow (e.g. "render-check the diagram; if a type does not support accTitle/accDescr, add the italic descriptive paragraph above and re-check") so error recovery is not left implicit.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient with tables and concrete rules, but the "core bet" paragraph, the Discord blockquote, and the "Why text-based diagrams win" advocacy table explain motivation Claude does not need, fitting the "mostly efficient but includes some unnecessary explanation" anchor rather than the lean-3 anchor.	2 / 3
Actionability	Provides copy-paste-ready Mermaid snippets (radar WRONG/CORRECT, three-phase flowchart), concrete mandatory rules (accTitle/accDescr format, no %%{init}, classDef only, snake_case IDs), and real exemplar file paths for the primary diagram-writing task — fully executable guidance.	3 / 3
Workflow Clarity	The 5-step core workflow is clearly sequenced and ends with a validation checklist, but Steps 1 ("Check if a template exists") and 4 ("Start from the template") reference a templates/ directory that is absent from the bundle, and there is no explicit validate→fix→retry feedback loop, fitting the "steps listed but validation gaps" anchor.	2 / 3
Progressive Disclosure	Reference organization is otherwise excellent — a clear index table pointing one level deep to 26 real files (2 style guides, 24 diagram guides, 1 example) — but the 9 referenced templates/*.md paths (cited in both the Step 1 table and the Reference index) do not exist in the bundle, so navigation is partially broken for a whole category.	2 / 3
	Total	9 / 12 Passed

Description

92%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, third-person description with explicit what/when triggers and natural keywords. Its main weakness is breadth: the "any scientific document, report, analysis, or visualization" trigger is wide enough to compete with sibling writing skills.

Suggestions

Narrow the trigger to lead with the distinguishing capability, e.g. "Use when creating markdown documents that need embedded Mermaid diagrams, or when visualizing workflows, architectures, or relationships as text-based diagrams," to reduce overlap with scientific-writing.

Lead the description with the concrete action (diagram/document creation) before the meta-claim about standards and bundle contents, so the differentiator is front-loaded.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions and artifacts — "creating any scientific document, report, analysis, or visualization" and "Establishes text-based diagrams as the default documentation standard with full style guides (markdown + mermaid), 24 diagram type references, and 9 document templates" — beyond the vague-anchor level.	3 / 3
Completeness	Explicitly answers both what ("Comprehensive markdown and Mermaid diagram writing skill... Establishes text-based diagrams as the default documentation standard") and when ("Use when creating any scientific document, report, analysis, or visualization"), satisfying the explicit-trigger bar.	3 / 3
Trigger Term Quality	Includes natural terms a user would actually say — "scientific document, report, analysis, or visualization" plus "markdown and Mermaid diagram" — giving good coverage rather than jargon.	3 / 3
Distinctiveness Conflict Risk	The Mermaid/diagram niche is distinctive, but the broad trigger "any scientific document, report, analysis, or visualization" overlaps with writing skills, and the body confirms integration with scientific-writing, scientific-schematics, and literature-review siblings — "somewhat specific but could still overlap with similar skills."	2 / 3
	Total	11 / 12 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
referenced_paths_exist	Referenced path issues: 26 deeper-than-1-level	Warning

	Total	15 / 16 Passed

Repository: K-Dense-AI/scientific-agent-skills
Path: skills/markdown-mermaid-writing/SKILL.md
Commit: 757b63b

Reviewed: about 11 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.