agentleFS
gyugyu90gyugyu90/DiaStream/.agents/skills/update-diagram/SKILL.md

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.

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
  1. Very specific:

    Use the bundled resolver from the DiaStream repository root:

    line 23
  2. Distinctive:

    Do not guess when resolution returns no file or multiple files.

    line 32
  3. Very specific:

    Update metadata.updatedAt to the current ISO 8601 UTC timestamp when that field exists.

    line 44
  4. Very specific:

    Before finishing a layout change, inspect edges and labels against node rectangles.

    line 59
  5. Very specific:

    Keep group membership only in Group.nodeIds.

    line 62
  6. Very specific:

    Keep animation membership only in Animation.edgeIds and do not repeat an edge ID within one animation.

    line 63
  7. Distinctive:

    When deleting a node, also delete or update edges that reference it, remove its ID from groups, and remove affected scene node overrides.

    line 64
  8. Very specific:

    When deleting an edge, remove its ID from animations and scene edge overrides.

    line 65
  9. Very specific:

    When deleting an animation, remove its ID from every scene's animationIds.

    line 66
  10. Distinctive:

    When changing ports, repair every edge endpoint that references the changed port.

    line 67
  11. Distinctive:

    Keep scenes as overrides over shared node and edge topology.

    line 68
  12. Very specific:

    Keep Scene.animationIds unique and preserve at most one node or edge override for each target in a scene.

    line 71
  13. Very specific:

    Put arbitrary extensions only in Node.data, Edge.data, or Animation.payload.

    line 72
  14. Distinctive:

    Do not make unrelated visual cleanup or schema migrations unless requested.

    line 73
  15. Very specific:

    After successful normalization and validation, check whether the local DiaStream development server is reachable at its expected local …

    line 77
  16. Very specific:

    If the server is running, report its URL and tell the user to open the updated .diagram.json through the editor.

    line 79
  17. Very specific:

    If the server is not running and the task is interactive, ask whether the user wants to start it.

    line 80
  18. Distinctive:

    If the user already requested a local preview or server startup, treat that as confirmation and do not ask again.

    line 81
  19. Distinctive:

    Do not treat preview availability or server startup failure as diagram-update failure.

    line 83
  20. Distinctive:

    Do not copy the diagram into application or public directories solely for preview.

    line 84

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. exact path
  2. exact filename
  3. exact metadata.title, case-insensitive
  4. 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

  1. Resolve one target file and read it completely.
  2. Validate the unchanged input from the DiaStream repository root:

    npm run diagrams:validate -- path/to/file.diagram.json
  3. Translate the request into the smallest JSON change. Preserve formatting style where practical.
  4. Update metadata.updatedAt to the current ISO 8601 UTC timestamp when that field exists. Do not invent createdAt or rewrite it.
  5. 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
  6. 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 labelPlacement when 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, info or palette presets blue, green, amber, red, violet, slate; edge colors may also use default. Use custom colors only as six-digit #rrggbb hex 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.edgeIds and 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 edgeIds array.
  • 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.animationIds unique and preserve at most one node or edge override for each target in a scene.
  • Put arbitrary extensions only in Node.data, Edge.data, or Animation.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.json through 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.