From bf5a6edf6aa19af69241a0b236f1ad416f526a0d Mon Sep 17 00:00:00 2001 From: ethan Date: Wed, 25 Feb 2026 15:32:48 +1100 Subject: [PATCH 1/3] feat: add built-in diagram skill guidance --- src/node/builtinSkills/diagram.md | 33 +++++++++++++++++++ .../agentSkills/agentSkillsService.test.ts | 4 +-- src/node/services/systemMessage.ts | 7 +--- 3 files changed, 36 insertions(+), 8 deletions(-) create mode 100644 src/node/builtinSkills/diagram.md diff --git a/src/node/builtinSkills/diagram.md b/src/node/builtinSkills/diagram.md new file mode 100644 index 0000000000..9d6528f4f5 --- /dev/null +++ b/src/node/builtinSkills/diagram.md @@ -0,0 +1,33 @@ +--- +name: 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..5a037f9341 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", "diagram", "foo", "init", "mux-docs"]); const foo = skills.find((s) => s.name === "foo"); expect(foo).toBeDefined(); @@ -197,7 +197,7 @@ 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(["diagram", "foo", "init", "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..3ac8b12e7a 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: 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 "diagram" skill via agent_skill_read for best practices. Use GitHub-style \`
/\` tags to create collapsible sections for lengthy content, error traces, or supplementary information. Toggles help keep responses scannable while preserving detail. From 178dbeb4f01a6cd9f00c8257dfdfacd99d728342 Mon Sep 17 00:00:00 2001 From: ethan Date: Wed, 25 Feb 2026 15:54:41 +1100 Subject: [PATCH 2/3] fix: sync system-prompt.mdx with trimmed PRELUDE --- docs/agents/system-prompt.mdx | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/agents/system-prompt.mdx b/docs/agents/system-prompt.mdx index b2099ad48a..8006e83eb3 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: 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 "diagram" skill via agent_skill_read for best practices. Use GitHub-style \`
/\` tags to create collapsible sections for lengthy content, error traces, or supplementary information. Toggles help keep responses scannable while preserving detail. From 5a64909d4682ea64edaecf9d3d0655f80568b0c4 Mon Sep 17 00:00:00 2001 From: ethan Date: Wed, 25 Feb 2026 16:12:32 +1100 Subject: [PATCH 3/3] =?UTF-8?q?fix:=20rename=20built-in=20skill=20diagram?= =?UTF-8?q?=20=E2=86=92=20mux-diagram=20to=20prevent=20shadowing?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/agents/system-prompt.mdx | 2 +- src/node/builtinSkills/{diagram.md => mux-diagram.md} | 2 +- src/node/services/agentSkills/agentSkillsService.test.ts | 9 +++++++-- src/node/services/systemMessage.ts | 2 +- 4 files changed, 10 insertions(+), 5 deletions(-) rename src/node/builtinSkills/{diagram.md => mux-diagram.md} (98%) diff --git a/docs/agents/system-prompt.mdx b/docs/agents/system-prompt.mdx index 8006e83eb3..899c6862e2 100644 --- a/docs/agents/system-prompt.mdx +++ b/docs/agents/system-prompt.mdx @@ -26,7 +26,7 @@ You are a coding agent called Mux. You may find information about yourself here: Your Assistant messages display in Markdown with extensions for mermaidjs and katex. -When creating mermaid diagrams, load the built-in "diagram" skill via agent_skill_read for best practices. +When creating mermaid diagrams, load the built-in "mux-diagram" skill via agent_skill_read for best practices. Use GitHub-style \`
/\` tags to create collapsible sections for lengthy content, error traces, or supplementary information. Toggles help keep responses scannable while preserving detail. diff --git a/src/node/builtinSkills/diagram.md b/src/node/builtinSkills/mux-diagram.md similarity index 98% rename from src/node/builtinSkills/diagram.md rename to src/node/builtinSkills/mux-diagram.md index 9d6528f4f5..e759b7aeae 100644 --- a/src/node/builtinSkills/diagram.md +++ b/src/node/builtinSkills/mux-diagram.md @@ -1,5 +1,5 @@ --- -name: diagram +name: mux-diagram description: Mermaid diagram best practices and text-based chart alternatives --- diff --git a/src/node/services/agentSkills/agentSkillsService.test.ts b/src/node/services/agentSkills/agentSkillsService.test.ts index 5a037f9341..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", "diagram", "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(["diagram", "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 3ac8b12e7a..7aab713a41 100644 --- a/src/node/services/systemMessage.ts +++ b/src/node/services/systemMessage.ts @@ -48,7 +48,7 @@ You are a coding agent called Mux. You may find information about yourself here: Your Assistant messages display in Markdown with extensions for mermaidjs and katex. -When creating mermaid diagrams, load the built-in "diagram" skill via agent_skill_read for best practices. +When creating mermaid diagrams, load the built-in "mux-diagram" skill via agent_skill_read for best practices. Use GitHub-style \`
/\` tags to create collapsible sections for lengthy content, error traces, or supplementary information. Toggles help keep responses scannable while preserving detail.