json-canvas

Présentation de la compétence json-canvas

À quoi sert la compétence json-canvas

La compétence json-canvas aide un agent IA à créer et modifier des fichiers .canvas conformes à la structure JSON Canvas 1.0 utilisée par les tableaux visuels de type Obsidian. Sa vraie valeur ne tient pas au “diagramming” au sens large, mais à la production d’un JSON nodes et edges valide, avec les bons IDs, coordonnées et références, pour que le fichier s’ouvre correctement au lieu de se casser de façon discrète.

À qui s’adresse json-canvas

Cette json-canvas skill convient surtout aux utilisateurs qui savent déjà quel résultat ils veulent obtenir — carte mentale, organigramme, tableau de projet, carte conceptuelle ou canvas de notes — sans vouloir rédiger le schéma à la main. Elle est particulièrement utile si vous travaillez dans Obsidian, gérez des fichiers .canvas dans un repo, ou cherchez des modifications reproductibles assistées par IA sur des canvases existants plutôt que des suggestions visuelles ponctuelles.

Pourquoi elle est préférable à un prompt générique

Un prompt classique peut décrire des boîtes et des flèches, mais il rate souvent des détails de format essentiels : IDs hexadécimaux uniques sur 16 caractères, références fromNode et toNode valides, placement sans chevauchement, et distinction entre nœuds de texte et nœuds de groupe. La compétence json-canvas donne à l’agent un format cible concret et des exemples, ce qui réduit nettement le travail de correction après génération.

Ce qu’il faut savoir avant de l’adopter

Cette compétence est volontairement ciblée. Elle aide à gérer la structure des fichiers .canvas et les workflows de modification les plus courants ; elle ne remplace ni un moteur complet de mise en page visuelle, ni un outil de diagrammes sémantiques, ni un optimiseur automatique de design. Si votre besoin principal est un rendu très soigné ou l’export vers de nombreux formats de diagramme, json-canvas for Diagramming peut sembler trop bas niveau. Si vous avez surtout besoin d’un JSON canvas valide rapidement, c’est un bon choix.

Comment utiliser la compétence json-canvas

Contexte d’installation et ordre de lecture recommandé

Pour utiliser json-canvas install dans un environnement compatible avec les skills, ajoutez la compétence depuis le repository kepano/obsidian-skills, puis lisez d’abord skills/json-canvas/SKILL.md et ensuite skills/json-canvas/references/EXAMPLES.md. Ces deux fichiers forment le cœur pratique du sujet : le premier explique la structure requise et les workflows, le second montre des exemples complets à reprendre comme modèles.

Quels éléments fournir pour bien utiliser json-canvas

La qualité d’usage de json-canvas usage dépend directement de la précision de votre demande. Indiquez :

• le chemin du fichier cible ou le contenu .canvas existant
• s’il s’agit d’un nouveau canvas ou d’une modification
• les types de nœuds souhaités, comme text ou group
• l’intention de mise en page, par exemple un flux de gauche à droite ou des colonnes kanban
• les connexions attendues entre les nœuds
• les contraintes de taille ou d’espacement

Une demande faible serait : “make a project canvas.” Une demande plus solide : “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.”

Transformer un besoin vague en prompt json-canvas solide

Pour obtenir un meilleur résultat avec json-canvas guide, demandez à la fois la génération et la validation. Un bon modèle de prompt est :

1. Énoncez l’objectif en langage clair.
2. Précisez s’il faut créer ou modifier.
3. Définissez l’inventaire des nœuds et leurs relations.
4. Demandez à l’agent de valider le JSON et les références d’arêtes avant la sortie finale.

Exemple :
“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.”

Conseils de workflow pratiques pour gagner du temps

Pour un meilleur json-canvas usage, commencez simple, puis itérez :

• Demandez d’abord un canvas minimal mais structurellement valide.
• Ouvrez-le ou inspectez-le.
• Puis demandez une seule modification à la fois : ajouter des nœuds, regrouper, reconnecter ou repositionner.

Si vous modifiez un fichier existant, dites à l’agent d’analyser les IDs actuels avant d’ajouter quoi que ce soit. Les problèmes les plus fréquents viennent des collisions d’IDs et des arêtes qui pointent vers des nœuds absents. Si la mise en page compte, demandez explicitement des règles d’espacement ; sinon, le JSON peut être valide tout en restant visuellement désordonné.

FAQ sur la compétence json-canvas

json-canvas convient-il aux débutants ?

Oui, si vous savez déjà ce que le canvas doit contenir. La compétence élimine l’essentiel des tâtonnements liés au schéma, ce qui permet aux débutants d’obtenir des fichiers .canvas valides sans mémoriser la spécification. Elle est moins adaptée si vous êtes encore en train de définir la logique du diagramme elle-même ; la compétence aide à encoder une structure, pas à inventer à votre place toute l’architecture de l’information.

Quand utiliser json-canvas plutôt qu’un prompt IA classique ?

Utilisez json-canvas lorsque la sortie doit être un fichier .canvas réellement exploitable, en particulier si vous modifiez un canvas existant. Un prompt générique peut aider à réfléchir à la structure, mais cette compétence est meilleure dès que la justesse technique compte : IDs uniques, tableaux valides, vraies références de nœuds et formatage compatible Obsidian.

json-canvas couvre-t-il tous les besoins de diagramming ?

Non. json-canvas for Diagramming fonctionne surtout pour les canvases à nœuds et arêtes, les tableaux simples et l’organisation visuelle liée à des notes. Ce n’est pas un substitut à des outils BPMN, à des visuels de présentation soignés, ni à des systèmes avancés de mise en page automatique. Si vous avez besoin de standards de diagramme étendus ou de contrôles de style riches, mieux vaut utiliser un autre outil, puis convertir si nécessaire.

Quelles sont les principales limites ou situations où ce n’est pas le bon choix ?

Évitez cette compétence si votre cible n’est pas un fichier .canvas, si vous avez besoin d’une optimisation poussée de la mise en page automatique, ou si la source de vérité doit rester dans un autre format comme Mermaid, Excalidraw ou une feuille de calcul. Évitez aussi les demandes vagues du type “make it look nice” ; la compétence fonctionne bien mieux quand la structure et l’intention de placement sont explicites.

Comment améliorer l’usage de la compétence json-canvas

Fournir des entrées structurelles plus solides

Le plus gros levier d’amélioration vient de la qualité de la structure fournie au départ. Nommez les nœuds voulus, les connexions entre eux et le schéma spatial attendu. Par exemple, “hub-and-spoke”, “three-column board” ou “timeline from left to right” donnent à l’agent assez d’informations pour placer les nœuds de façon cohérente au lieu d’improviser.

Éviter les modes d’échec les plus courants

La plupart des problèmes avec json-canvas sont mécaniques :

• IDs dupliqués
• arêtes pointant vers des nœuds inexistants
• coordonnées qui se chevauchent
• champs requis manquants comme type, x, y, width, height

Demandez à l’agent de valider tous les IDs et toutes les références avant de renvoyer le fichier. Si vous modifiez un canvas, indiquez-lui de conserver les IDs existants, sauf si la modification impose un nouveau nœud ou une nouvelle arête.

Itérer après la première sortie

Traitez le premier résultat comme une base de travail. Ensuite, améliorez une couche à la fois :

• ajuster l’espacement et l’alignement
• ajouter des groupes
• affiner les libellés et le contenu textuel
• ajouter ou supprimer des connexions

Cette approche fonctionne mieux que de demander d’un seul coup un canvas final dense, car les erreurs de structure visuelle se repèrent plus facilement tôt dans le processus qu’après une génération volumineuse.

S’appuyer volontairement sur les exemples et les patterns du repository

Pour améliorer les résultats avec la json-canvas skill, reprenez les formes présentes dans references/EXAMPLES.md au lieu de tout décrire de manière abstraite. Si la sortie souhaitée ressemble à un tableau de projet, demandez à l’agent de suivre le pattern basé sur des groupes. Si elle ressemble à une carte conceptuelle, demandez le pattern simple de nœuds de texte connectés. Réutiliser les patterns natifs du repository produit en général un JSON plus propre et moins de surprises de compatibilité.