mermaid
**UTILITY SKILL** — Mermaid diagrams for inline markdown: flowcharts, sequence, Gantt, class, state, ER. WHEN: "mermaid flowchart", "sequence diagram", "Gantt chart", "state diagram", "ER diagram", "inline markdown diagram". DO NOT USE FOR: Azure-icon architecture diagrams (drawio), WAF/cost charts (python-diagrams).
66
78%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.github/skills/mermaid/SKILL.mdQuality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that hits all the key criteria. It specifies concrete diagram types, includes natural trigger terms users would say, explicitly defines both when to use and when NOT to use the skill, and clearly distinguishes itself from related diagramming tools. The 'DO NOT USE FOR' clause is a particularly strong addition for disambiguation in a multi-skill environment.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete diagram types: flowcharts, sequence, Gantt, class, state, ER diagrams. Also specifies the output format (inline markdown) and the tool (Mermaid). | 3 / 3 |
Completeness | Clearly answers both 'what' (Mermaid diagrams for inline markdown covering multiple diagram types) and 'when' (explicit WHEN clause with trigger phrases). Also includes a 'DO NOT USE FOR' clause that further clarifies scope boundaries. | 3 / 3 |
Trigger Term Quality | Includes highly natural trigger terms users would actually say: 'mermaid flowchart', 'sequence diagram', 'Gantt chart', 'state diagram', 'ER diagram', 'inline markdown diagram'. These cover the main variations well. | 3 / 3 |
Distinctiveness Conflict Risk | Excellent distinctiveness with explicit negative boundaries ('DO NOT USE FOR: Azure-icon architecture diagrams (drawio), WAF/cost charts (python-diagrams)') that directly address potential overlap with other diagramming skills. The Mermaid + inline markdown niche is clearly carved out. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is well-structured with good progressive disclosure and clear scope boundaries, but it lacks concrete executable examples — no actual Mermaid code block is shown despite being a diagram-authoring skill. The workflow is present but the validation step is vague without error recovery guidance. Some content is repeated across sections (scope exclusions echo DON'T rules, 'When to Use' echoes the intro).
Suggestions
Add at least one concrete Mermaid diagram example (e.g., a simple flowchart in a ```mermaid fence) to make the skill immediately actionable without needing to load references.
Strengthen the validation step with specific error recovery: what common syntax errors look like, how to fix them, and a validate-then-fix loop before committing.
Remove the 'Scope Exclusions' section or merge it into the DON'T rules to eliminate redundancy and save tokens.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient but has some redundancy — the 'When to Use Mermaid' section largely repeats information from the intro and description. The 'Scope Exclusions' section also repeats DON'T rules. The DO/DON'T format is compact though. | 2 / 3 |
Actionability | Provides a clear workflow and references to cheatsheets, but lacks any concrete code examples — no actual Mermaid diagram snippet is shown inline. A simple flowchart or sequence diagram example would make this copy-paste ready. | 2 / 3 |
Workflow Clarity | Steps are clearly sequenced (pick type → author → style → validate → commit), but the validation step is vague ('render in VS Code preview or Starlight build') with no feedback loop for syntax errors or recovery guidance. | 2 / 3 |
Progressive Disclosure | Clean overview with a well-organized reference index table pointing to one-level-deep references (syntax-cheatsheet.md and styling.md). Navigation is clearly signaled with both inline links and a summary table. | 3 / 3 |
Total | 9 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- jonathan-vella/azure-agentic-infraops
- Commit
05d7617
- 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.