CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

markdown-mermaid-writing

Writes scientific Markdown documentation and Mermaid diagrams for workflows, relationships, timelines, and schemas. Provides syntax references, document templates, accessibility guidance, and version-aware rendering checks. Use when a user requests Markdown, Mermaid, or a text-based structural diagram; quantitative scientific figures require suitable plotting tools.

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

67%Weight 40%Scale 1-5

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 and actionable, with a clear five-step workflow, strong routing to verified one-level-deep reference files, and excellent concrete pitfall examples. The main defects are padded marketing content (a Discord quote and a philosophy comparison table that duplicate the usage guidance), the absence of an explicit render-failure feedback loop, and a broken templates/ directory referenced for nine document templates.

Suggestions

Remove or trim the Discord quote and the 'Source Format Philosophy' comparison table — their decision-relevant content (use Mermaid for structure, plotting tools for data) is already covered by 'When to Use This Skill' — and consolidate the diagram-type table with the reference index listing to eliminate duplication.

Fix the templates/ references: either include the nine template files (pull_request.md, issue.md, kanban.md, decision_record.md, presentation.md, research_paper.md, project_documentation.md, how_to_guide.md, status_report.md) in the bundle or remove the Step 1 template table and reference-index entry pointing to them.

Add an explicit validation feedback loop in Step 4: state what to do when the destination fails to render a chosen diagram type (e.g., fall back to a supported type or export SVG/PNG with a text alternative and re-check), completing the checkpoint pattern already started by 'Render in the actual destination before delivery'.

DimensionReasoningScore

Conciseness

The core workflow steps, radar pitfall examples, and dense comparison tables are efficient, but the body carries unnecessary material: a promotional Discord quote ("The more you get your reports and files in .md in just regular text..."), a "Source Format Philosophy" section whose Mermaid-vs-Python comparison table largely duplicates the 'When to Use This Skill' guidance, and a diagram-type listing repeated between the type-selection table and the reference index. This fits 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than the notably verbose level 2, since the majority of sections are actionable.

3 / 5

Actionability

Concrete, executable guidance dominates: a copy-paste accTitle/accDescr snippet, WRONG/CORRECT radar-beta syntax examples, an XY-vs-radar keyword/axis/data comparison table, and explicit file pointers for every step. It is not a 5 because Step 1 directs readers to nine template paths (templates/pull_request.md, templates/issue.md, etc.) whose directory does not exist in the bundle — a concrete gap in the primary workflow.

4 / 5

Workflow Clarity

The five-step core workflow is clearly sequenced (identify document type → read style guide → pick diagram type → write → retain source) with an explicit validation checkpoint — "Render in the actual destination before delivery. Check its Mermaid version and plugin requirements" — plus a finalization checklist. It falls short of anchor 5 because there is no explicit feedback loop for what to do when destination rendering fails; the fallback ("supply a rendered SVG/PNG") is stated but error-recovery steps are implicit.

4 / 5

Progressive Disclosure

Measured against the actual bundle: the SKILL.md body is a genuine overview that routes to one-level-deep references — 24 verified files under references/diagrams/, three style guides in references/, and assets/examples/example-research-report.md — with clear navigation tables and a reference index. It is not a 5 because the nine templates/*.md files referenced in both Step 1 and the reference index are missing from the bundle, breaking navigation for a substantial set of advertised resources.

4 / 5

Total

15

/

20

Passed

Description

83%Weight 40%Scale 1-5

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 description: third-person, concise, explicitly answering both what the skill does and when to use it, with concrete trigger phrases and a clear boundary excluding quantitative plotting. The only weaknesses are minor — a few missing natural trigger variations (no .md extension or 'flowchart') and a slightly broad Markdown trigger that could overlap with general documentation skills.

DimensionReasoningScore

Specificity

The description lists several concrete actions — "Writes scientific Markdown documentation and Mermaid diagrams for workflows, relationships, timelines, and schemas" plus "Provides syntax references, document templates, accessibility guidance, and version-aware rendering checks" — matching the 'several specific actions; minor gaps in coverage' anchor. It falls short of 5 because capabilities like maintaining rendered SVG/PNG exports are not mentioned, and 'Provides syntax references' describes skill contents rather than an action Claude performs.

4 / 5

Completeness

Both questions are explicitly answered: the 'what' is stated in two sentences of concrete capabilities, and the 'when' is an explicit trigger clause — "Use when a user requests Markdown, Mermaid, or a text-based structural diagram" — reinforced by a negative boundary ("quantitative scientific figures require suitable plotting tools"). This matches the anchor-5 example structure of concrete what-and-when with trigger phrases.

5 / 5

Trigger Term Quality

Natural trigger terms are present — "Markdown", "Mermaid", "text-based structural diagram", "workflows, relationships, timelines, schemas", "quantitative scientific figures" — giving good keyword coverage. It is not a 5 because common variations users would say are missing: no file extension (.md), no 'flowchart', 'diagram' alone, or 'README'.

4 / 5

Distinctiveness Conflict Risk

The Markdown/Mermaid structural-diagram niche is distinct with clear triggers and an explicit boundary against plotting tools. It is not a 5 because "a user requests Markdown" is broad and would fire on plain Markdown writing requests that general documentation or writing skills could equally serve — minor overlap risk with closely related skills.

4 / 5

Total

17

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

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

Reviewed

Table of Contents

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.