Agent skill
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.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/debug-connection
SKILL.md
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:
nodesas array - IR format:
nodesas 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"}
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?