json-canvas

Tổng quan về skill json-canvas

Skill json-canvas làm được gì

json-canvas giúp AI agent tạo và chỉnh sửa các file .canvas theo cấu trúc JSON Canvas 1.0 dùng trong các bảng trực quan kiểu Obsidian. Giá trị thực sự của skill này không nằm ở việc “vẽ sơ đồ nói chung”, mà ở khả năng tạo ra JSON nodes và edges hợp lệ với đúng ID, tọa độ và tham chiếu để file mở lên ổn định, thay vì lỗi theo những cách khó phát hiện.

Ai nên cài json-canvas

json-canvas skill phù hợp nhất với người dùng đã biết mình muốn đầu ra là gì — như mind map, flowchart, bảng dự án, concept map hoặc note canvas — nhưng không muốn tự viết schema bằng tay. Skill này đặc biệt hữu ích nếu bạn làm việc trong Obsidian, lưu .canvas trong repo, hoặc muốn có quy trình chỉnh sửa canvas hiện có bằng AI một cách lặp lại được, thay vì chỉ nhận vài gợi ý trực quan dùng một lần.

Vì sao nó tốt hơn một prompt chung chung

Một prompt thông thường có thể mô tả các ô và mũi tên, nhưng thường bỏ sót những chi tiết định dạng rất quan trọng: ID hex 16 ký tự duy nhất, tham chiếu fromNode và toNode hợp lệ, cách đặt phần tử không chồng lấn, và khác biệt giữa text node với group node. json-canvas cung cấp cho agent một định dạng đích cụ thể cùng ví dụ tham chiếu, nhờ đó giảm đáng kể công sửa lỗi sau khi sinh nội dung.

Những điều cần biết trước khi dùng

Skill này được thiết kế theo hướng hẹp và chuyên dụng. Nó hỗ trợ cấu trúc file .canvas và các workflow chỉnh sửa phổ biến; nó không thay thế một visual layout engine đầy đủ, công cụ semantic diagramming, hay hệ thống tối ưu bố cục tự động. Nếu nhu cầu chính của bạn là style đẹp mắt hoặc xuất sang nhiều định dạng sơ đồ khác nhau, json-canvas for Diagramming có thể sẽ hơi quá low-level. Nhưng nếu điều bạn cần là tạo JSON canvas hợp lệ thật nhanh, đây là lựa chọn rất phù hợp.

Cách dùng skill json-canvas

Cài đặt trong ngữ cảnh phù hợp và nên đọc gì trước

Để dùng json-canvas install trong môi trường có hỗ trợ skills, hãy thêm skill từ repository kepano/obsidian-skills, sau đó đọc skills/json-canvas/SKILL.md trước và skills/json-canvas/references/EXAMPLES.md sau. Đây là hai file quan trọng nhất về mặt thực hành: file đầu giải thích cấu trúc bắt buộc và các workflow chính, còn file sau đưa ra các ví dụ hoàn chỉnh để bạn đối chiếu theo mẫu.

json-canvas cần đầu vào gì để hoạt động tốt

Chất lượng json-canvas usage phụ thuộc nhiều vào mức độ cụ thể của yêu cầu. Hãy cung cấp:

• đường dẫn file đích hoặc nội dung .canvas hiện có
• bạn muốn tạo canvas mới hay chỉnh sửa canvas cũ
• các loại node cần dùng, chẳng hạn text hoặc group
• ý đồ bố cục tổng quát, như luồng trái sang phải hoặc các cột kanban
• các kết nối mong muốn giữa các node
• mọi yêu cầu về kích thước hoặc khoảng cách

Một yêu cầu yếu là: “make a project canvas.”
Một yêu cầu mạnh hơn là: “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.”

Cách biến mục tiêu mơ hồ thành prompt mạnh cho json-canvas

Để nâng chất lượng json-canvas guide, hãy yêu cầu cả phần sinh nội dung lẫn phần kiểm tra hợp lệ. Một mẫu prompt hiệu quả là:

1. Nêu mục tiêu bằng tiếng Anh đơn giản.
2. Chỉ rõ là tạo mới hay chỉnh sửa.
3. Xác định danh sách node và quan hệ giữa chúng.
4. Yêu cầu agent kiểm tra JSON và các tham chiếu edge trước khi trả kết quả cuối.

Ví dụ:
“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.”

Mẹo workflow thực tế giúp tiết kiệm thời gian

Để json-canvas usage hiệu quả hơn, hãy bắt đầu đơn giản rồi lặp từng bước:

• Trước tiên yêu cầu một canvas tối thiểu nhưng hợp lệ về cấu trúc.
• Mở file hoặc kiểm tra nó.
• Sau đó mới yêu cầu từng thay đổi một: thêm node, nhóm lại, nối lại, hoặc đổi vị trí.

Nếu chỉnh sửa file đang có, hãy yêu cầu agent phân tích các ID hiện tại trước khi thêm bất cứ thứ gì. Lỗi phổ biến nhất là trùng ID và edge trỏ tới node không tồn tại. Nếu bố cục quan trọng, hãy nêu rõ quy tắc về khoảng cách; nếu không, JSON có thể hợp lệ nhưng nhìn rất lộn xộn.

Câu hỏi thường gặp về skill json-canvas

json-canvas có phù hợp cho người mới bắt đầu không?

Có, nếu bạn đã biết canvas của mình cần chứa những gì. Skill này loại bỏ phần lớn việc phải tự đoán schema, nên người mới vẫn có thể tạo file .canvas hợp lệ mà không cần học thuộc spec. Tuy nhiên, nó kém phù hợp hơn nếu bạn vẫn đang loay hoay xác định logic sơ đồ; skill này giúp mã hóa cấu trúc, chứ không tự nghĩ giúp bạn toàn bộ thiết kế thông tin.

Khi nào nên dùng json-canvas thay vì prompt AI thông thường?

Hãy dùng json-canvas khi đầu ra bắt buộc phải là một file .canvas chạy được, đặc biệt là khi chỉnh sửa canvas đã có sẵn. Prompt chung có thể hữu ích để brainstorm cấu trúc, nhưng skill này tốt hơn khi tính đúng đắn là yếu tố quan trọng: ID duy nhất, mảng hợp lệ, tham chiếu node có thật và định dạng tương thích với Obsidian.

json-canvas có đáp ứng mọi nhu cầu vẽ sơ đồ không?

Không. json-canvas for Diagramming phù hợp nhất cho canvas dạng node-edge, bảng đơn giản và cách tổ chức trực quan gắn với ghi chú. Nó không thay thế các công cụ BPMN, phần mềm đồ họa trình bày trau chuốt, hay hệ thống auto-layout nâng cao. Nếu bạn cần chuẩn sơ đồ rộng hơn hoặc kiểm soát style phong phú hơn, hãy dùng công cụ khác và chỉ chuyển đổi sang định dạng này khi thực sự cần.

Những giới hạn chính hoặc trường hợp không phù hợp là gì?

Bạn nên bỏ qua skill này nếu đích đến không phải file .canvas, nếu bạn cần tối ưu bố cục tự động ở mức nặng, hoặc nếu nguồn dữ liệu chuẩn phải tiếp tục nằm ở định dạng khác như Mermaid, Excalidraw hay bảng tính. Ngoài ra, cũng nên tránh các prompt mơ hồ như “make it look nice”; skill này hoạt động tốt nhất khi cấu trúc và ý định bố trí được nêu rõ ràng.

Cách cải thiện skill json-canvas

Cung cấp đầu vào cấu trúc rõ hơn cho json-canvas

Nâng cấp đầu ra mạnh nhất đến từ việc bạn cung cấp cấu trúc tốt hơn ngay từ đầu. Hãy nêu rõ những node bạn muốn có, các kết nối giữa chúng và mô hình không gian mong muốn. Ví dụ như “hub-and-spoke”, “three-column board” hoặc “timeline from left to right” sẽ cho agent đủ thông tin để đặt node hợp lý thay vì phải tự đoán.

Ngăn các lỗi phổ biến nhất

Phần lớn lỗi của json-canvas mang tính cơ học:

• ID bị trùng
• edge trỏ tới node không tồn tại
• tọa độ chồng lấn lên nhau
• thiếu các trường bắt buộc như type, x, y, width, height

Hãy yêu cầu agent kiểm tra toàn bộ ID và tham chiếu trước khi trả file. Nếu đang chỉnh sửa một canvas, hãy yêu cầu giữ nguyên các ID hiện có trừ khi thay đổi đó thực sự cần tạo node hoặc edge mới.

Lặp lại sau đầu ra đầu tiên

Hãy xem kết quả đầu tiên như một bộ khung. Sau đó cải thiện từng lớp một:

• chỉnh khoảng cách và căn hàng
• thêm group
• tinh chỉnh nhãn và nội dung text
• thêm hoặc bớt kết nối

Cách này hiệu quả hơn nhiều so với việc yêu cầu một canvas hoàn chỉnh dày đặc ngay từ đầu, vì lỗi về cấu trúc trực quan luôn dễ phát hiện sớm hơn là sau một lần sinh lớn.

Dùng ví dụ và pattern trong repository một cách chủ đích

Để cải thiện kết quả của json-canvas skill, hãy mượn các mẫu từ references/EXAMPLES.md thay vì mô tả mọi thứ một cách trừu tượng. Nếu đầu ra bạn muốn giống một bảng dự án, hãy yêu cầu agent bám theo pattern dùng group. Nếu nó giống một concept map, hãy yêu cầu pattern text-node kết nối đơn giản. Tái sử dụng các pattern có sẵn trong repository thường cho ra JSON sạch hơn và ít gặp bất ngờ về tương thích hơn.