How do I install the Debug Connection skill?

Run npx skillmds@latest add tomevault-io/debug-connection in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Debug Connection safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Debug Connection?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Debug Connection free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Debug Connection?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Debug Connection by tomevault-io — Agent Skill

Name: Debug Connection
Author: tomevault-io

Debug Connection

Debug WebSocket connection issues between CLI and FigJam plugin. Use when diagrams aren't syncing, connection fails, plugin shows "Connecting..." indefinitely, or patches aren't being applied to canvas. Use when this capability is needed.

tomevault-io Updated Sep 17, 2026

File contents

WebSocket Connection Debugging

Architecture

CLI serve (Bun) ←── WebSocket ──→ Plugin UI (ui.ts) ←── postMessage ──→ Plugin Main (code.ts)
     │                                  │                                    │
  File watcher                    Browser APIs                          Figma API
  YAML parsing                    WebSocket client                      Canvas rendering

Common Issues

Issue	Symptom	Solution
CLI not running	"Connecting..." indefinitely	Start `bun run packages/cli/src/index.ts serve diagram.yaml`
Port in use	Connection refused	Check `lsof -i :3456`, use different port
Secret mismatch	Connects then immediately closes	Match `--secret` value in CLI and plugin
YAML errors	Connected but no updates	Fix validation errors in CLI output
docId mismatch	No response after hello	Ensure plugin docId matches YAML `docId`
Patches not applied	Connected, canvas unchanged	Check Plugin Main console for render errors

Debugging Steps

CLI side: Check terminal for errors, verify YAML with bun run packages/cli/src/index.ts build diagram.yaml
Plugin UI: Right-click plugin → Inspect → Console for WebSocket events
Plugin Main: Figma Desktop → Plugins → Development → Open console

Message Flow

Plugin                          CLI
  │                              │
  │──── hello ─────────────────►│  {type:"hello", docId, secret?}
  │◄──── full ─────────────────│  {type:"full", rev, ir}
  │                              │
  │      [YAML changes]          │
  │◄──── patch ────────────────│  {type:"patch", baseRev, nextRev, ops}
  │                              │
  │      [Reconnect]             │
  │──── requestFull ───────────►│  {type:"requestFull", docId}
  │◄──── full ─────────────────│

JSON Import Errors

JSON must be an object with version, docId, nodes
DSL format: nodes as array
IR format: nodes as object (Record)
Validation errors shown in alert with path + message

Quick Test

# Start server
bun run packages/cli/src/index.ts serve examples/diagram.yaml

# Test with wscat
wscat -c ws://localhost:3456
> {"type":"hello","docId":"test"}

Converted and distributed by TomeVault — claim your Tome and manage your conversions.

---name: debug-connectiondescription: Debug WebSocket connection issues between CLI and FigJam plugin. Use when diagrams aren't syncing, connection fails, plugin shows "Connecting..." indefinitely, or patches aren't being applied to canvas. Use when this capability is needed.---# WebSocket Connection Debugging## Architecture```CLI serve (Bun) ←── WebSocket ──→ Plugin UI (ui.ts) ←── postMessage ──→ Plugin Main (code.ts) │ │ │ File watcher Browser APIs Figma API YAML parsing WebSocket client Canvas rendering```## Common Issues| Issue | Symptom | Solution ||-------|---------|----------|| CLI not running | "Connecting..." indefinitely | Start `bun run packages/cli/src/index.ts serve diagram.yaml` || Port in use | Connection refused | Check `lsof -i :3456`, use different port || Secret mismatch | Connects then immediately closes | Match `--secret` value in CLI and plugin || YAML errors | Connected but no updates | Fix validation errors in CLI output || docId mismatch | No response after hello | Ensure plugin docId matches YAML `docId` || Patches not applied | Connected, canvas unchanged | Check Plugin Main console for render errors |## Debugging Steps1. **CLI side**: Check terminal for errors, verify YAML with `bun run packages/cli/src/index.ts build diagram.yaml`2. **Plugin UI**: Right-click plugin → Inspect → Console for WebSocket events3. **Plugin Main**: Figma Desktop → Plugins → Development → Open console## Message Flow```Plugin CLI │ │ │──── hello ─────────────────►│ {type:"hello", docId, secret?} │◄──── full ─────────────────│ {type:"full", rev, ir} │ │ │ [YAML changes] │ │◄──── patch ────────────────│ {type:"patch", baseRev, nextRev, ops} │ │ │ [Reconnect] │ │──── requestFull ───────────►│ {type:"requestFull", docId} │◄──── full ─────────────────│```## JSON Import Errors- JSON must be an object with `version`, `docId`, `nodes`- DSL format: `nodes` as array- IR format: `nodes` as object (Record)- Validation errors shown in alert with path + message## Quick Test```bash# Start serverbun run packages/cli/src/index.ts serve examples/diagram.yaml# Test with wscatwscat -c ws://localhost:3456> {"type":"hello","docId":"test"}```---> Converted and distributed by [TomeVault](https://tomevault.io/claim/7nohe) — claim your Tome and manage your conversions.

Frequently asked questions