json-canvas
by kepanojson-canvas helps create and edit valid .canvas files for Obsidian-style boards, with correct nodes, edges, IDs, coordinates, groups, and references.
This skill scores 76/100, which means it is a solid directory listing candidate: agents get a clear trigger, concrete file-format guidance, and example-backed execution help that should reduce guesswork versus a generic prompt, though users should expect mostly document-based guidance rather than tooling or enforcement.
- Strong triggerability from the frontmatter and description: it explicitly targets creating and editing Obsidian `.canvas` files, visual canvases, mind maps, flowcharts, and Canvas mentions.
- Operationally useful format guidance: `SKILL.md` explains the top-level `nodes`/`edges` structure, required fields, ID rules, connection validation, and common edit workflows like creating canvases, adding nodes, and connecting nodes.
- Good progressive disclosure through worked examples: `references/EXAMPLES.md` provides complete JSON examples for connected text nodes and grouped board-style layouts, helping agents infer valid structure quickly.
- Implementation support is documentation-only: there are no scripts, install commands, rules files, or validation helpers, so agents still need to translate prose into exact edits on their own.
- Workflow depth appears uneven: structural signals show limited explicit workflow/constraint coverage, so edge cases and decision rules may be less robust than the document length suggests.
Overview of json-canvas skill
What the json-canvas skill does
The json-canvas skill helps an AI agent create and edit .canvas files that follow the JSON Canvas 1.0 structure used by Obsidian-style visual boards. Its real value is not “diagramming in general,” but producing valid nodes and edges JSON with the right IDs, coordinates, and references so the file opens cleanly instead of breaking in subtle ways.
Who should install json-canvas
This json-canvas skill is best for users who already know the outcome they want—a mind map, flowchart, project board, concept map, or note canvas—but do not want to hand-author the schema. It is especially useful if you work in Obsidian, maintain .canvas files in a repo, or want repeatable AI-assisted edits to existing canvases rather than one-off visual suggestions.
Why it is better than a generic prompt
A normal prompt may describe boxes and arrows, but it often misses format details that matter: unique 16-character hex IDs, valid fromNode and toNode references, non-overlapping placement, and the difference between text nodes and group nodes. The json-canvas skill gives the agent a concrete target format and examples, which reduces repair work after generation.
What to know before adopting it
This skill is narrow by design. It helps with .canvas file structure and common edit workflows; it does not replace a full visual layout engine, semantic diagramming tool, or automatic design optimizer. If your main need is polished styling or export to many diagram formats, json-canvas for Diagramming may feel too low-level. If your need is valid canvas JSON fast, it is a good fit.
How to Use json-canvas skill
Install context and where to read first
To use json-canvas install in a skills-enabled environment, add the skill from the kepano/obsidian-skills repository, then read skills/json-canvas/SKILL.md first and skills/json-canvas/references/EXAMPLES.md second. Those two files are the practical core: the first explains required structure and workflows, and the second shows complete examples you can pattern-match against.
What input the skill needs to work well
The json-canvas usage quality depends on how specific your request is. Give:
- the target file path or existing
.canvascontent - whether you want a new canvas or an edit
- node types you need, such as
textorgroup - rough layout intent, such as left-to-right flow or kanban columns
- desired connections between nodes
- any size or spacing expectations
A weak request is “make a project canvas.” A stronger one is: “Create a new .canvas with three group columns labeled To Do, In Progress, Done, each 300x500, spaced 50px apart, and add three text task nodes inside the first two groups.”
How to turn a rough goal into a strong prompt
For json-canvas guide quality, ask for both generation and validation. A strong prompt pattern is:
- State the goal in plain English.
- Specify whether to create or modify.
- Define node inventory and relationships.
- Ask the agent to validate JSON and edge references before final output.
Example:
“Use the json-canvas skill to create a new .canvas file for a product launch plan. Add one central text node, four supporting text nodes around it, connect each support node to the center, keep 100px spacing to avoid overlap, generate unique 16-character hex IDs, and return valid JSON only.”
Practical workflow tips that save time
For better json-canvas usage, start simple, then iterate:
- First ask for a structurally valid minimal canvas.
- Open or inspect it.
- Then request one change at a time: add nodes, regroup, reconnect, or reposition.
If editing an existing file, tell the agent to parse the current IDs before adding anything. The most common breakage comes from ID collisions and edges pointing to missing nodes. If layout matters, explicitly request spacing rules; otherwise the JSON may be valid but visually messy.
json-canvas skill FAQ
Is json-canvas good for beginners?
Yes, if you already know what a canvas should contain. The skill removes most schema guesswork, so beginners can get valid .canvas files without memorizing the spec. It is less ideal if you are still deciding the diagram logic itself; the skill helps encode structure, not invent the entire information design for you.
When should I use json-canvas instead of a normal AI prompt?
Use json-canvas when the output must be a working .canvas file, especially when editing an existing canvas. A generic prompt can brainstorm structure, but this skill is better when correctness matters: unique IDs, valid arrays, real node references, and Obsidian-compatible formatting.
Does json-canvas handle all diagramming needs?
No. json-canvas for Diagramming is best for node-edge canvases, simple boards, and note-linked visual organization. It is not a substitute for BPMN tools, polished presentation graphics, or advanced auto-layout systems. If you need broad diagram standards or rich styling controls, use another tool and convert only if needed.
What are the main boundaries or misfit cases?
Skip this skill if your target is not a .canvas file, if you need heavy automatic layout optimization, or if the source of truth should remain in another format like Mermaid, Excalidraw, or a spreadsheet. Also avoid vague prompts like “make it look nice”; the skill performs best with explicit structure and placement intent.
How to Improve json-canvas skill
Give stronger structural inputs
The biggest output upgrade comes from supplying better structure up front. Name the nodes you want, the connections between them, and the intended spatial pattern. For example, “hub-and-spoke,” “three-column board,” or “timeline from left to right” gives the agent enough information to place nodes sensibly instead of guessing.
Prevent the common failure modes
Most json-canvas problems are mechanical:
- duplicate IDs
- edges pointing to nonexistent nodes
- overlapping coordinates
- missing required fields like
type,x,y,width,height
Ask the agent to validate all IDs and references before returning the file. If modifying a canvas, tell it to preserve existing IDs unless a change requires a new node or edge.
Iterate after the first output
Treat the first result as a scaffold. Then improve one layer at a time:
- adjust spacing and alignment
- add groups
- refine labels and text content
- add or remove connections
This works better than requesting a dense final canvas in one shot, because visual structure errors are easier to catch early than after a large generation.
Use examples and repository patterns deliberately
To improve json-canvas skill results, borrow shapes from references/EXAMPLES.md instead of describing everything abstractly. If your desired output resembles a project board, ask the agent to follow the group-based pattern. If it resembles a concept map, ask for the simple connected text-node pattern. Reusing repository-native patterns usually produces cleaner JSON and fewer compatibility surprises.