mermaid-markdown

Files (1)

• SKILL.md

SKILL.md (first lines)

# Mermaid Markdown

## Purpose

Draw the diagram or chart the human actually needs to understand, then implant it directly into the Markdown file where it belongs.

The goal is communication, not completeness.

This is a supporting skill. It visualizes understanding, decisions, relationships, and quantitative results that already exist. It does not perform architecture design, project planning, new statistical analysis, or alternative evaluation.

> Draw the visual the human actually wants to understand.

> The simplest visual that communicates that clearly is the correct visual.

---

# When To Use

Use this skill when the user explicitly wants a Mermaid diagram or Mermaid chart added to or updated in a Markdown file.

Examples:

- "Add an architecture diagram to this task."
- "Put the worker flow into `docs/architecture.md`."
- "Add a Mermaid diagram showing how this request works."
- "Diagram the job lifecycle in this plan."
- "Add a chart comparing the benchmark results."
- "Show these evaluation scores as a Mermaid chart."
- "Plot the before vs after metrics."
- "Update the diagram in this Markdown."
- "Add a diagram here."

The normal output is a Mermaid fenced block directly inside the target `.md` file:

````markdown
```mermaid
flowchart LR
    User --> API
    API --> Worker
    Worker --> Database
```
````

Do not create a separate `.mmd`, `.svg`, image, or `diagrams/` artifact unless the user explicitly asks for one.

---

# Boundary: Visualize, Do Not Design Or Reinterpret

This skill runs after the relevant system, workflow, plan, or quantitative result is understood well enough to visualize.

It may inspect relevant tasks, docs, plans, repository files, experiment outputs, benchmark results, or implementation evidence to understand what should be drawn.

It must not use visualization as an excuse to redesign the underlying system or reinterpret the underlying results.

Do not:

- choose a new architecture;
- reopen settled architecture decisions;
- evaluate competing implementation approaches;
- invent missing system behavior;
- change responsibilities or boundaries merely to improve the diagram;
- perform new statistical analysis that the source material does not support;
- change, normalize, aggregate, or selectively omit quantitative results merely to make a chart look better;
- invent statistical significance, confidence, or causality;
- expand into general planning.

If the source material reveals a material contradiction, missing relationship, unclear value, or ambiguous quantitative comparison, surface it instead of silently resolving it in the visual.

A diagram or chart must not look more certain than the evidence behind it.

---

# Clarify The Intended Visual When Needed

A request for "a diagram", "a chart", or "plot these results" may have several valid interpretations.

The skill's first responsibility is therefore to understand:

> **What should the human be able to see immediately from this visual?**

For structural diagrams, that may be:

- the overall architecture;
- an end-to-end process flow;
- a request or job sequence;
- a state lifecycle;
- a deployment view;
- a data flow;
- a specific subsystem.

For quantitative results, that may be:

- which result is largest or smallest;
- which model wins;
- how much something improved;
- whether a candidate beat a baseline;
- how values changed over time;
- whether a target was met;
- the exact absolute values;
- the size and direction of a regression.

Infer this from the request and surrounding Markdown when it is obvious.

Do not ask the user to choose Mermaid syntax or chart type when the skill can choose it.

If two materially different visual messages are plausible and the surrounding context does not resolve them, ask one concise question about the intended comparison.

Good:

> "Do you want this to emphasize the absolute before/after scores, or how much each metric changed?"

> "Should the reader mainly see which model wins, or the trade-off between accuracy and latency?"

Bad:

> "Do you want a bar chart or a line chart?"

The human decides what they want to understand.

From chingfhen/agent-core, MIT.

More from chingfhen/agent-core