update-diagram
Skill1 starsChanged 3 months agoMITView on GitHub
Find and safely update an existing DiaStream .diagram.json file while preserving stable IDs and reference integrity. Use when the user asks to change, edit, revise, rename, extend, or remove content from a diagram identified by path, filename, metadata title, or natural-language context.
In this repository2 other files it gives its agents.
- AGENTS.mdAGENTS.md
- create-diagramSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. About 0 are common, 8 are distinctive, and 12 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
Use the bundled resolver from the DiaStream repository root:
- Distinctive: line 32
Do not guess when resolution returns no file or multiple files.
- Very specific: line 44
Update metadata.updatedAt to the current ISO 8601 UTC timestamp when that field exists.
- Very specific: line 59
Before finishing a layout change, inspect edges and labels against node rectangles.
- Very specific: line 62
Keep group membership only in Group.nodeIds.
- Very specific: line 63
Keep animation membership only in Animation.edgeIds and do not repeat an edge ID within one animation.
- Distinctive: line 64
When deleting a node, also delete or update edges that reference it, remove its ID from groups, and remove affected scene node overrides.
- Very specific: line 65
When deleting an edge, remove its ID from animations and scene edge overrides.
- Very specific: line 66
When deleting an animation, remove its ID from every scene's animationIds.
- Distinctive: line 67
When changing ports, repair every edge endpoint that references the changed port.
- Distinctive: line 68
Keep scenes as overrides over shared node and edge topology.
- Very specific: line 71
Keep Scene.animationIds unique and preserve at most one node or edge override for each target in a scene.
- Very specific: line 72
Put arbitrary extensions only in Node.data, Edge.data, or Animation.payload.
- Distinctive: line 73
Do not make unrelated visual cleanup or schema migrations unless requested.
- Very specific: line 77
After successful normalization and validation, check whether the local DiaStream development server is reachable at its expected local …
- Very specific: line 79
If the server is running, report its URL and tell the user to open the updated .diagram.json through the editor.
- Very specific: line 80
If the server is not running and the task is interactive, ask whether the user wants to start it.
- Distinctive: line 81
If the user already requested a local preview or server startup, treat that as confirmation and do not ask again.
- Distinctive: line 83
Do not treat preview availability or server startup failure as diagram-update failure.
- Distinctive: line 84
Do not copy the diagram into application or public directories solely for preview.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Update DiaStream Diagram
Resolve exactly one existing Diagram JSON document, make the smallest requested change, and validate the result. Keep Diagram JSON as the source of truth; never replace it with SVG, HTML, Canvas code, or an image.
Compatibility
Target DiaStream schemaVersion: "0.2". Read packages/schema/src/index.ts or schemas/diagram.schema.json before changing schema-sensitive fields.
Identify The Target
Accept selectors written naturally or as explicit prompt fields such as path:, filename:, and title:. Resolve them in this order:
- exact path
- exact filename
- exact
metadata.title, case-insensitive - filename or title explicitly contained in the natural-language request
Use the bundled resolver from the DiaStream repository root:
node .agents/skills/update-diagram/scripts/find-diagram.mjs --root . --path diagrams/api.diagram.json
node .agents/skills/update-diagram/scripts/find-diagram.mjs --root . --filename api.diagram.json
node .agents/skills/update-diagram/scripts/find-diagram.mjs --root . --title "API Overview"
node .agents/skills/update-diagram/scripts/find-diagram.mjs --root . --query "Update the API Overview diagram"Do not guess when resolution returns no file or multiple files. Show the candidates and ask for a path or filename. Never update multiple diagrams unless the user explicitly requests a batch change.
Workflow
- Resolve one target file and read it completely.
Validate the unchanged input from the DiaStream repository root:
npm run diagrams:validate -- path/to/file.diagram.json- Translate the request into the smallest JSON change. Preserve formatting style where practical.
- Update
metadata.updatedAtto the current ISO 8601 UTC timestamp when that field exists. Do not inventcreatedAtor rewrite it. Normalize and validate the edited file. Fix every structural and reference-integrity error before finishing.
npm run diagrams:normalize -- path/to/file.diagram.json npm run diagrams:validate -- path/to/file.diagram.json- Report the resolved path, concise changes, and validation result.
Preservation Rules
- Preserve IDs for existing entities, even when labels or titles change. Add a new stable ID only for a new entity.
- Preserve unrelated fields, ordering, extension data, viewport, theme, and scene behavior.
- When the request affects layout, use generous spacing between node rectangles and reserve clear corridors for edge labels and group boundaries. For hubs with three or more distributed neighbors, prefer a polygonal layout such as a hexagon over one crowded straight rail; send branches and return paths through distinct upper, lower, or diagonal lanes.
- Before finishing a layout change, inspect edges and labels against node rectangles. Move nodes farther apart or change
labelPlacementwhen a label overlaps, is clipped by, or appears visually attached to a node. Do not reposition unrelated nodes for content-only edits. - Preserve an existing custom or legacy icon ID unless the requested change affects that icon. Use a supported namespaced
material-symbols:*ID for new icon choices; do not invent unsupported IDs. - Use only supported color values when changing theme or edge colors. Preserve existing valid colors unless the request affects them. Prefer semantic presets
accent,primary,muted,neutral,success,warning,danger,infoor palette presetsblue,green,amber,red,violet,slate; edge colors may also usedefault. Use custom colors only as six-digit#rrggbbhex values. Do not use CSS named colors,rgb(),hsl(), or short hex. - Keep group membership only in
Group.nodeIds; do not repeat a node ID or place one node in multiple groups. - Keep animation membership only in
Animation.edgeIdsand do not repeat an edge ID within one animation. - When deleting a node, also delete or update edges that reference it, remove its ID from groups, and remove affected scene node overrides.
- When deleting an edge, remove its ID from animations and scene edge overrides. Remove or adjust animations that would otherwise have an empty
edgeIdsarray. - When deleting an animation, remove its ID from every scene's
animationIds. - When changing ports, repair every edge endpoint that references the changed port.
- Keep scenes as overrides over shared node and edge topology; do not duplicate the full graph per scene. Use node overrides for scene-specific label, type, icon, position, tone, or status changes, and edge overrides for scene-specific label, style, tone, or disabled-state changes.
- Keep
Scene.animationIdsunique and preserve at most one node or edge override for each target in a scene. - Put arbitrary extensions only in
Node.data,Edge.data, orAnimation.payload; structural objects are strict. - Do not make unrelated visual cleanup or schema migrations unless requested.
Optional Local Preview
After successful normalization and validation, check whether the local DiaStream development server is reachable at its expected local address without starting it.
- If the server is running, report its URL and tell the user to open the updated
.diagram.jsonthrough the editor. - If the server is not running and the task is interactive, ask whether the user wants to start it. Start it from the DiaStream repository root only after confirmation, then report the actual URL printed by the development server.
- If the user already requested a local preview or server startup, treat that as confirmation and do not ask again.
- Skip the preview offer for batch, CI, or explicitly file-only requests.
- Do not treat preview availability or server startup failure as diagram-update failure.
- Do not copy the diagram into application or public directories solely for preview.
Output Boundary
Modify only the resolved .diagram.json file unless validation requires a directly related repair. Do not modify runtime or editor source while carrying out a diagram-content request.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

