Skip to content

aiskillstore/marketplace / skills/7nohe/debug-connection

debug-connection

Verified

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.

FileKindSize
SKILL.mdskill md2.7 KB
skill-report.jsonconfig18.2 KB

skill-report.json

View on GitHub
{
  "schema_version": "2.0",
  "meta": {
    "generated_at": "2026-07-04T17:27:11.740Z",
    "slug": "7nohe-debug-connection",
    "source_url": "https://github.com/7nohe/figram/tree/main/.claude/skills/debug-connection",
    "source_ref": "main",
    "model": "codex",
    "analysis_version": "3.0.0",
    "source_type": "community",
    "content_hash": "cc715e606519385afc7362d7437983916c8ef9e6ffca47e58271faecdc0916e0",
    "tree_hash": "44fcdb725c20f583932b1b63ccb853084549128034ee335cccdd541555327497",
    "provenance": {
      "model_effective": "codex",
      "fallback_chain": [
        {
          "agent": "codex",
          "outcome": "success"
        }
      ],
      "analysis_version": "3.0.0"
    }
  },
  "skill": {
    "name": "debug-connection",
    "description": "Debug WebSocket connection issues between a CLI server and FigJam plugin, including sync failures, stalled connections, and patch problems.",
    "summary": "Guide agents through FigJam plugin WebSocket connection debugging.",
    "icon": "📦",
    "version": "1.0.1",
    "author": "7nohe",
    "license": "MIT",
    "tags": [
      "websocket",
      "figjam",
      "cli",
      "debugging",
      "plugin-development"
    ],
    "supported_tools": [
      "claude",
      "codex",
      "claude-code"
    ],
    "risk_factors": [
      "external_commands"
    ],
    "category": "coding"
  },
  "security_audit": {
    "risk_level": "safe",
    "is_blocked": false,
    "safe_to_publish": true,
    "analysis_status": "ok",
    "summary": "All 13 static findings are false positives from Markdown code fences or inline literals in SKILL.md. The skill provides local WebSocket debugging guidance and hardcoded diagnostic commands; no prompt injection, exfiltration, or dynamic execution intent was found.",
    "remediation": [],
    "risk_factor_evidence": [
      {
        "factor": "external_commands",
        "evidence": [
          {
            "file": "SKILL.md",
            "line_start": 10,
            "line_end": 15
          },
          {
            "file": "SKILL.md",
            "line_start": 15,
            "line_end": 21
          },
          {
            "file": "SKILL.md",
            "line_start": 21,
            "line_end": 22
          },
          {
            "file": "SKILL.md",
            "line_start": 22,
            "line_end": 23
          },
          {
            "file": "SKILL.md",
            "line_start": 23,
            "line_end": 25
          },
          {
            "file": "SKILL.md",
            "line_start": 25,
            "line_end": 30
          },
          {
            "file": "SKILL.md",
            "line_start": 30,
            "line_end": 36
          },
          {
            "file": "SKILL.md",
            "line_start": 36,
            "line_end": 48
          },
          {
            "file": "SKILL.md",
            "line_start": 48,
            "line_end": 52
          },
          {
            "file": "SKILL.md",
            "line_start": 52,
            "line_end": 52
          },
          {
            "file": "SKILL.md",
            "line_start": 53,
            "line_end": 54
          },
          {
            "file": "SKILL.md",
            "line_start": 54,
            "line_end": 59
          },
          {
            "file": "SKILL.md",
            "line_start": 59,
            "line_end": 66
          }
        ]
      }
    ],
    "static_findings": [
      {
        "id": "external_commands:SKILL.md:10:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 10,
        "line_end": 15,
        "snippet": "```"
      },
      {
        "id": "external_commands:SKILL.md:15:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 15,
        "line_end": 21,
        "snippet": "```"
      },
      {
        "id": "external_commands:SKILL.md:21:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 21,
        "line_end": 22,
        "snippet": "| CLI not running | \"Connecting...\" indefinitely | Start `bun run packages/cli/src/index.ts serve di"
      },
      {
        "id": "external_commands:SKILL.md:22:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 22,
        "line_end": 23,
        "snippet": "| Port in use | Connection refused | Check `lsof -i :3456`, use different port |"
      },
      {
        "id": "external_commands:SKILL.md:23:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 23,
        "line_end": 25,
        "snippet": "| Secret mismatch | Connects then immediately closes | Match `--secret` value in CLI and plugin |"
      },
      {
        "id": "external_commands:SKILL.md:25:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 25,
        "line_end": 30,
        "snippet": "| docId mismatch | No response after hello | Ensure plugin docId matches YAML `docId` |"
      },
      {
        "id": "external_commands:SKILL.md:30:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 30,
        "line_end": 36,
        "snippet": "1. **CLI side**: Check terminal for errors, verify YAML with `bun run packages/cli/src/index.ts buil"
      },
      {
        "id": "external_commands:SKILL.md:36:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 36,
        "line_end": 48,
        "snippet": "```"
      },
      {
        "id": "external_commands:SKILL.md:48:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 48,
        "line_end": 52,
        "snippet": "```"
      },
      {
        "id": "external_commands:SKILL.md:52:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 52,
        "line_end": 52,
        "snippet": "- JSON must be an object with `version`, `docId`, `nodes`"
      },
      {
        "id": "external_commands:SKILL.md:53:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 53,
        "line_end": 54,
        "snippet": "- DSL format: `nodes` as array"
      },
      {
        "id": "external_commands:SKILL.md:54:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 54,
        "line_end": 59,
        "snippet": "- IR format: `nodes` as object (Record)"
      },
      {
        "id": "external_commands:SKILL.md:59:ruby-shell-backtick-execution",
        "category": "external_commands",
        "severity": "medium",
        "pattern": "Ruby/shell backtick execution",
        "file": "SKILL.md",
        "line_start": 59,
        "line_end": 66,
        "snippet": "```bash"
      }
    ],
    "finding_verdicts": [
      {
        "id": "external_commands:SKILL.md:10:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.96,
        "reason": "The snippet is a Markdown code fence for an architecture diagram, not executable Ruby or shell backtick syntax. It does not ask the agent to run code."
      },
      {
        "id": "external_commands:SKILL.md:15:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.96,
        "reason": "The snippet closes the Markdown architecture diagram code fence, not a shell execution construct. No command or user input is executed."
      },
      {
        "id": "external_commands:SKILL.md:21:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.9,
        "reason": "This is a hardcoded local Bun CLI command shown as troubleshooting guidance. It contains no untrusted interpolation, secret handling, or exfiltration target."
      },
      {
        "id": "external_commands:SKILL.md:22:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.9,
        "reason": "This is a local port inspection command shown for a port conflict. It does not include remote network access, credentials, or dynamic arguments."
      },
      {
        "id": "external_commands:SKILL.md:23:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.88,
        "reason": "The backticks mark option names in Markdown. The line advises matching a secret value locally and does not expose or transmit it."
      },
      {
        "id": "external_commands:SKILL.md:25:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.95,
        "reason": "The backticks mark the YAML docId field in prose. No shell execution or dynamic command construction appears."
      },
      {
        "id": "external_commands:SKILL.md:30:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.9,
        "reason": "This is a hardcoded local build command for validating a diagram file. It does not include untrusted shell interpolation or external exfiltration."
      },
      {
        "id": "external_commands:SKILL.md:36:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.96,
        "reason": "The snippet is a Markdown code fence for a message-flow diagram. It is documentation text, not executable shell or Ruby syntax."
      },
      {
        "id": "external_commands:SKILL.md:48:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.96,
        "reason": "The snippet closes a Markdown message-flow diagram code fence. It does not create an execution path."
      },
      {
        "id": "external_commands:SKILL.md:52:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.95,
        "reason": "The backticks mark JSON field names in documentation. There is no command execution or dynamic code evaluation."
      },
      {
        "id": "external_commands:SKILL.md:53:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.95,
        "reason": "The backticks mark the nodes field name in prose. This is a formatting false positive, not an execution primitive."
      },
      {
        "id": "external_commands:SKILL.md:54:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.95,
        "reason": "The backticks mark the nodes field name in prose. No shell command, Ruby backtick execution, or untrusted input execution is present."
      },
      {
        "id": "external_commands:SKILL.md:59:ruby-shell-backtick-execution",
        "verdict": "false_positive",
        "confidence": 0.86,
        "reason": "The bash block contains local Bun server and localhost WebSocket test commands for diagnostics. The commands are fixed examples with no hidden execution or injection vector."
      }
    ],
    "semantic_findings": [],
    "critical_findings": [],
    "high_findings": [],
    "medium_findings": [],
    "low_findings": [],
    "dangerous_patterns": [],
    "files_scanned": 1,
    "total_lines": 67,
    "audit_model": "codex",
    "audited_at": "2026-07-04T17:27:11.740Z",
    "agent_auto_install_policy": "allowed",
    "manual_install_policy": "allowed"
  },
  "content": {
    "user_title": "Debug FigJam WebSocket Connections",
    "value_statement": "FigJam plugin development can fail when the CLI, WebSocket server, and plugin consoles disagree. This skill gives a focused checklist for diagnosing connection, sync, and patch problems.",
    "seo_keywords": [
      "Claude",
      "Codex",
      "Claude Code",
      "FigJam WebSocket debugging",
      "Figma plugin connection",
      "CLI sync troubleshooting",
      "diagram sync issues",
      "wscat WebSocket test",
      "Bun CLI debugging",
      "plugin console diagnostics"
    ],
    "actual_capabilities": [
      "Explains the CLI, plugin UI, and plugin main connection flow.",
      "Maps common symptoms to likely causes and local checks.",
      "Guides inspection of CLI output, plugin UI console, and Figma development console.",
      "Documents WebSocket hello, full, patch, and request-full message flow.",
      "Lists JSON import expectations for DSL and IR node formats.",
      "Provides a quick local WebSocket test using the configured server port."
    ],
    "limitations": [
      "Does not include executable helper scripts or automated diagnostics.",
      "Assumes the project uses the FigJam plugin architecture described in the skill.",
      "Does not resolve WebSocket server bugs without access to project source code.",
      "Requires local tools such as Bun or a WebSocket client for some checks."
    ],
    "use_cases": [
      {
        "title": "Restore Diagram Sync",
        "description": "Diagnose why diagram changes do not reach the FigJam canvas.",
        "target_user": "Plugin developer"
      },
      {
        "title": "Triage Console Errors",
        "description": "Compare CLI, plugin UI, and plugin main logs during connection failures.",
        "target_user": "Developer debugging a local plugin"
      },
      {
        "title": "Validate WebSocket Setup",
        "description": "Check ports, secrets, document identifiers, and test client behavior.",
        "target_user": "Developer onboarding a workspace"
      }
    ],
    "prompt_templates": [
      {
        "title": "Basic Connection Check",
        "scenario": "Beginner check for a stalled plugin connection.",
        "prompt": "Help me debug a FigJam plugin that stays on Connecting. Ask for the CLI output, plugin UI console, and server port."
      },
      {
        "title": "Sync Failure Triage",
        "scenario": "Intermediate diagnosis for connected plugins without canvas updates.",
        "prompt": "A diagram connects but canvas updates do not appear. Walk through likely causes using the debug-connection checklist."
      },
      {
        "title": "Message Flow Review",
        "scenario": "Advanced review of WebSocket sequencing.",
        "prompt": "Review my FigJam plugin WebSocket flow. Check hello, full, patch, and reconnect behavior against the expected sequence."
      },
      {
        "title": "Full Incident Diagnosis",
        "scenario": "Advanced multi-cause debugging plan.",
        "prompt": "Create a step-by-step diagnosis plan for CLI errors, port conflicts, secret mismatch, docId mismatch, and patch failures."
      }
    ],
    "output_examples": [
      {
        "input": "The plugin shows Connecting and the CLI window is quiet.",
        "output": [
          "Confirm the local server is running on the expected port.",
          "Inspect the plugin UI console for connection errors.",
          "Check that the plugin targets the same document and port."
        ]
      },
      {
        "input": "The canvas does not update after diagram changes.",
        "output": [
          "Check CLI validation output for diagram errors.",
          "Inspect the plugin main console for render failures.",
          "Verify that patch messages are received after the initial full update."
        ]
      },
      {
        "input": "A manual WebSocket test connects but no full update arrives.",
        "output": [
          "Compare the document identifier used by the client and source file.",
          "Check whether a shared secret is required on both sides.",
          "Request a fresh full update after reconnecting."
        ]
      }
    ],
    "best_practices": [
      "Check the CLI, plugin UI, and plugin main consoles before changing source code.",
      "Verify secrets, document identifiers, and ports with the same values on both sides.",
      "Reproduce failures with a minimal diagram before debugging complex content."
    ],
    "anti_patterns": [
      "Assuming the canvas renderer is broken before checking connection state.",
      "Changing several connection settings at once during diagnosis.",
      "Ignoring validation errors from the CLI build step."
    ],
    "faq": [
      {
        "question": "What problems does this skill help with?",
        "answer": "It helps debug FigJam plugin connection, sync, and patch application failures."
      },
      {
        "question": "Does it run commands automatically?",
        "answer": "No. It provides guidance and command examples for local debugging."
      },
      {
        "question": "Can it fix Figma account or permission issues?",
        "answer": "No. It focuses on local plugin connection behavior and project diagnostics."
      },
      {
        "question": "Does it cover JSON import errors?",
        "answer": "Yes. It documents expected JSON structure for DSL and IR node formats."
      },
      {
        "question": "Can Claude, Codex, or Claude Code use it?",
        "answer": "Yes. The report lists support for Claude, Codex, and Claude Code."
      },
      {
        "question": "What should I collect before using it?",
        "answer": "Collect CLI output, plugin UI console logs, plugin main console logs, and connection settings."
      }
    ]
  },
  "file_structure": [
    {
      "name": "SKILL.md",
      "type": "file",
      "path": "SKILL.md",
      "lines": 67
    }
  ]
}
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall