markdown-mermaid-writing

Comprehensive markdown and Mermaid diagram writing skill that establishes text-based diagrams as the DEFAULT documentation standard. Use this skill when creating ANY scientific document, report, analysis, or visualization — it ensures all outputs are in version-controlled, token-efficient markdown with embedded Mermaid diagrams as the source of truth, with clear pathways to downstream Python or AI-generated images. Includes full style guides (markdown + mermaid), 24 diagram type references, and 9 document templates ready to use.

Quality

75%

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 ./bundled/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.

The body is well-structured with good progressive disclosure to real diagram/style references and concrete mandatory rules. Its main gaps are a missing templates/ bundle that breaks the primary workflow, no validation checkpoints in the commit workflow, and some verbosity in the philosophy/quote sections.

Suggestions

Add the missing templates/ directory (pull_request.md, issue.md, etc.) or remove the template table and Step 1 instruction — the current state sends Claude to files that do not exist.

Insert a verification checkpoint into the Core workflow (e.g., Step 4.5: render/preview the Mermaid and run the style checklist before committing) to satisfy the validation-loop expectation for structural output.

Trim the philosophy section, Discord quote, and 'Why text-based diagrams win' table to a few lines — Claude already understands git-diff and token-efficiency tradeoffs.

Dimension	Reasoning	Score
Conciseness	Mostly efficient tables and short directives, but it spends tokens on a philosophy section, an attributed Discord quote, a full 'Why text-based diagrams win' comparison table, and a three-phase Mermaid diagram that largely restates concepts Claude already knows; could be tightened without losing actionable value.	2 / 3
Actionability	Gives concrete mandatory rules (accTitle/accDescr format, no %%{init}, classDef only, snake_case IDs) and a WRONG/CORRECT radar example, but Step 1's template table points at a templates/ directory that does not exist in the bundle, so the central 'start from the template' instruction is not actually executable.	2 / 3
Workflow Clarity	A clear 5-step Core workflow is present and a final checklist exists, but there are no validation/feedback checkpoints: Step 4 'write the document' and Step 5 'commit' have no verify-render or lint step, and the rubric caps workflow clarity at 2 when batch/structural operations lack validation loops.	2 / 3
Progressive Disclosure	SKILL.md is a well-organized overview with one-level-deep references to real files (style guides and 24 diagram guides confirmed present), but the 9 referenced templates are missing from the bundle entirely, so navigation signaled in the body leads to non-existent files.	2 / 3
	Total	8 / 12 Passed

Description

85%

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

The description is concrete, third-person, and clearly states both capabilities and explicit 'Use when' triggers with natural phrasing. Its main weakness is over-claiming with 'ANY ... ANY ... ANY' framing that blurs distinctiveness against general documentation skills.

Suggestions

Tighten the trigger scope: replace the repeated 'ANY' clauses with the specific document/diagram types where Mermaid-as-source-of-truth genuinely applies, reducing conflict with general writing skills.

Lead with the one-line differentiator (Mermaid-in-markdown as version-controlled source of truth) before the bundle inventory so the niche is unambiguous.

Trim the bundle-size inventory ('24 diagram type references, 9 document templates') from the description — it pads length without aiding trigger matching.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions/bundle contents — '24 diagram type references', '9 document templates', 'style guides (markdown + mermaid)', and establishes markdown+Mermaid as the documentation format with pathways to Python/AI images.	3 / 3
Completeness	Explicitly answers both what ('establishes text-based diagrams as the DEFAULT documentation standard') and when ('Use this skill when creating ANY scientific document...'), with an explicit 'Use when' clause present.	3 / 3
Trigger Term Quality	Natural trigger terms are well covered: 'scientific document, report, analysis, or visualization', 'diagram', 'markdown', and explicit 'Use this skill when creating ANY...' phrasing mirrors how a user would phrase the request.	3 / 3
Distinctiveness Conflict Risk	The trigger scope is extremely broad — 'Creating ANY scientific document... ANY documentation... ANY diagram... ANY output... Working with ANY other skill' — which over-claims and would conflict with general writing/documentation skills; it is somewhat specific to Mermaid/markdown but the 'ANY' framing weakens distinction.	2 / 3
	Total	11 / 12 Passed

Validation

81%

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 — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning
metadata_field	'metadata' should map string keys to string values	Warning
referenced_paths_exist	Referenced path issues: 26 deeper-than-1-level	Warning

	Total	13 / 16 Passed

Repository: foryourhealth111-pixel/Vibe-Skills
Path: bundled/skills/markdown-mermaid-writing/SKILL.md
Commit: f627ab5

Reviewed: about 7 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.