diff --git a/docs/agents/system-prompt.mdx b/docs/agents/system-prompt.mdx
index b2099ad48a..899c6862e2 100644
--- a/docs/agents/system-prompt.mdx
+++ b/docs/agents/system-prompt.mdx
@@ -26,12 +26,7 @@ You are a coding agent called Mux. You may find information about yourself here:
 <markdown>
 Your Assistant messages display in Markdown with extensions for mermaidjs and katex.
 
-When creating mermaid diagrams:
-- Avoid side-by-side subgraphs (they display too wide)
-- For comparisons, use separate diagram blocks or single graph with visual separation
-- When using custom fill colors, include contrasting color property (e.g., "style note fill:#ff6b6b,color:#fff")
-- Make good use of visual space: e.g. use inline commentary
-- Wrap node labels containing brackets or special characters in quotes (e.g., Display["Message[]"] not Display[Message[]])
+When creating mermaid diagrams, load the built-in "mux-diagram" skill via agent_skill_read for best practices.
 
 Use GitHub-style \`<details>/<summary>\` tags to create collapsible sections for lengthy content, error traces, or supplementary information. Toggles help keep responses scannable while preserving detail.
 </markdown>
diff --git a/src/node/builtinSkills/mux-diagram.md b/src/node/builtinSkills/mux-diagram.md
new file mode 100644
index 0000000000..e759b7aeae
--- /dev/null
+++ b/src/node/builtinSkills/mux-diagram.md
@@ -0,0 +1,33 @@
+---
+name: mux-diagram
+description: Mermaid diagram best practices and text-based chart alternatives
+---
+
+# Diagrams & Charts
+
+Use this skill when creating diagrams, flowcharts, or chart-like visualizations.
+
+## Mermaid (rendered)
+
+The app renders fenced `mermaid` code blocks as interactive diagrams.
+
+Best practices:
+
+- Avoid side-by-side subgraphs (they display too wide)
+- For comparisons, use separate diagram blocks or single graph with visual separation
+- When using custom fill colors, include contrasting color property (e.g., `style note fill:#ff6b6b,color:#fff`)
+- Make good use of visual space: e.g. use inline commentary
+- Wrap node labels containing brackets or special characters in quotes (e.g., `Display["Message[]"]` not `Display[Message[]]`)
+
+Supported diagram types: flowchart, sequence, class, state, ER, Gantt, pie, git graph, mindmap, timeline, sankey, and more. Choose the type that best fits the data.
+
+## Text-based alternatives (no rendering required)
+
+Not every visualization needs Mermaid. Prefer lightweight formats when they suffice:
+
+- **Markdown tables** — best for structured comparisons, feature matrices, or tabular data
+- **Bulleted/numbered lists** — best for hierarchies, step sequences, or simple trees
+- **Indented tree notation** — for directory structures or shallow hierarchies
+- **ASCII/Unicode bars** — quick inline quantitative comparisons (e.g., `████░░ 67%`)
+
+Choose Mermaid when relationships, flow, or topology matter. Choose text when the data is tabular or sequential.
diff --git a/src/node/services/agentSkills/agentSkillsService.test.ts b/src/node/services/agentSkills/agentSkillsService.test.ts
index 7970aab156..6e20ae68c1 100644
--- a/src/node/services/agentSkills/agentSkillsService.test.ts
+++ b/src/node/services/agentSkills/agentSkillsService.test.ts
@@ -43,7 +43,7 @@ describe("agentSkillsService", () => {
 
     // Should include project/global skills plus built-in skills
     // Note: deep-review skill is a project skill in the Mux repo, not a built-in
-    expect(skills.map((s) => s.name)).toEqual(["bar", "foo", "init", "mux-docs"]);
+    expect(skills.map((s) => s.name)).toEqual(["bar", "foo", "init", "mux-diagram", "mux-docs"]);
 
     const foo = skills.find((s) => s.name === "foo");
     expect(foo).toBeDefined();
@@ -197,7 +197,12 @@ describe("agentSkillsService", () => {
 
     const diagnostics = await discoverAgentSkillsDiagnostics(runtime, project.path, { roots });
 
-    expect(diagnostics.skills.map((s) => s.name)).toEqual(["foo", "init", "mux-docs"]);
+    expect(diagnostics.skills.map((s) => s.name)).toEqual([
+      "foo",
+      "init",
+      "mux-diagram",
+      "mux-docs",
+    ]);
 
     const invalidNames = diagnostics.invalidSkills.map((issue) => issue.directoryName).sort();
     expect(invalidNames).toEqual(
diff --git a/src/node/services/systemMessage.ts b/src/node/services/systemMessage.ts
index be7a18ca1c..7aab713a41 100644
--- a/src/node/services/systemMessage.ts
+++ b/src/node/services/systemMessage.ts
@@ -48,12 +48,7 @@ You are a coding agent called Mux. You may find information about yourself here:
 <markdown>
 Your Assistant messages display in Markdown with extensions for mermaidjs and katex.
 
-When creating mermaid diagrams:
-- Avoid side-by-side subgraphs (they display too wide)
-- For comparisons, use separate diagram blocks or single graph with visual separation
-- When using custom fill colors, include contrasting color property (e.g., "style note fill:#ff6b6b,color:#fff")
-- Make good use of visual space: e.g. use inline commentary
-- Wrap node labels containing brackets or special characters in quotes (e.g., Display["Message[]"] not Display[Message[]])
+When creating mermaid diagrams, load the built-in "mux-diagram" skill via agent_skill_read for best practices.
 
 Use GitHub-style \`<details>/<summary>\` tags to create collapsible sections for lengthy content, error traces, or supplementary information. Toggles help keep responses scannable while preserving detail.
 </markdown>