Agent skill

figma-debug-bundle

Collect Figma API diagnostic evidence for support tickets and troubleshooting. Use when encountering persistent issues, preparing support tickets, or collecting diagnostic information for Figma API problems. Trigger with phrases like "figma debug", "figma support bundle", "collect figma logs", "figma diagnostic".

Stars 1,803
Forks 241

Install this agent skill to your Project

npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/figma-pack/skills/figma-debug-bundle

SKILL.md

Figma Debug Bundle

Overview

Collect all diagnostic data needed to troubleshoot Figma REST API issues or submit a support request. Outputs a redacted archive with connectivity tests, token validation, rate limit status, and API response samples.

Prerequisites

  • FIGMA_PAT environment variable set
  • curl and jq available
  • A Figma file key to test against

Instructions

Step 1: Create Debug Bundle Script

bash
#!/bin/bash
# figma-debug-bundle.sh
set -euo pipefail

BUNDLE_DIR="figma-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== Figma Debug Bundle ===" | tee "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE_DIR/summary.txt"
echo "---" >> "$BUNDLE_DIR/summary.txt"

# 1. Environment info
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "Node: $(node --version 2>/dev/null || echo 'not installed')" >> "$BUNDLE_DIR/summary.txt"
echo "npm: $(npm --version 2>/dev/null || echo 'not installed')" >> "$BUNDLE_DIR/summary.txt"
echo "OS: $(uname -srm)" >> "$BUNDLE_DIR/summary.txt"
echo "PAT configured: ${FIGMA_PAT:+YES (${#FIGMA_PAT} chars)}" >> "$BUNDLE_DIR/summary.txt"
echo "File key: ${FIGMA_FILE_KEY:-NOT SET}" >> "$BUNDLE_DIR/summary.txt"

# 2. API connectivity test
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Connectivity ---" >> "$BUNDLE_DIR/summary.txt"
echo -n "GET /v1/me: " >> "$BUNDLE_DIR/summary.txt"
curl -s -o "$BUNDLE_DIR/me.json" -w "%{http_code} %{time_total}s" \
  -H "X-Figma-Token: ${FIGMA_PAT}" \
  https://api.figma.com/v1/me >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# 3. File access test (if key is set)
if [ -n "${FIGMA_FILE_KEY:-}" ]; then
  echo -n "GET /v1/files: " >> "$BUNDLE_DIR/summary.txt"
  curl -s -o "$BUNDLE_DIR/file-meta.json" -w "%{http_code} %{time_total}s" \
    -H "X-Figma-Token: ${FIGMA_PAT}" \
    "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}?depth=1" >> "$BUNDLE_DIR/summary.txt"
  echo "" >> "$BUNDLE_DIR/summary.txt"
fi

# 4. Rate limit check (capture response headers)
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Rate Limit Headers ---" >> "$BUNDLE_DIR/summary.txt"
curl -s -D "$BUNDLE_DIR/headers.txt" -o /dev/null \
  -H "X-Figma-Token: ${FIGMA_PAT}" \
  https://api.figma.com/v1/me
grep -iE "(rate|retry|figma)" "$BUNDLE_DIR/headers.txt" >> "$BUNDLE_DIR/summary.txt" 2>/dev/null || echo "No rate limit headers" >> "$BUNDLE_DIR/summary.txt"

# 5. Redact sensitive data
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Redaction ---" >> "$BUNDLE_DIR/summary.txt"
# Remove email from /v1/me response
if [ -f "$BUNDLE_DIR/me.json" ]; then
  jq '{handle: .handle, id: .id, img_url: "[REDACTED]", email: "[REDACTED]"}' \
    "$BUNDLE_DIR/me.json" > "$BUNDLE_DIR/me-redacted.json" 2>/dev/null || true
  rm -f "$BUNDLE_DIR/me.json"
fi

# Remove raw headers (may contain token in other tools)
rm -f "$BUNDLE_DIR/headers.txt"

echo "Redaction complete" >> "$BUNDLE_DIR/summary.txt"

# 6. Package
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
rm -rf "$BUNDLE_DIR"
echo "Bundle created: $BUNDLE_DIR.tar.gz"

Step 2: Run the Bundle

bash
chmod +x figma-debug-bundle.sh
./figma-debug-bundle.sh

Step 3: Review Before Sharing

bash
# Inspect the bundle contents
tar -tzf figma-debug-*.tar.gz
# Extract and review
tar -xzf figma-debug-*.tar.gz
cat figma-debug-*/summary.txt

Output

  • figma-debug-YYYYMMDD-HHMMSS.tar.gz containing:
    • summary.txt -- environment, connectivity, rate limit status
    • me-redacted.json -- authenticated user (email redacted)
    • file-meta.json -- file metadata (if file key provided)

Error Handling

Item What It Catches Why It Matters
/v1/me response code Token validity 403 = expired/invalid PAT
/v1/files response code File access 404 = wrong key, 403 = not shared
Rate limit headers Throttling state Retry-After shows if currently limited
Response time Latency issues >2s suggests network or server problems

Examples

ALWAYS REDACT Before Sharing

  • Personal access tokens (figd_*)
  • Email addresses
  • OAuth client secrets
  • File content (unless relevant to the bug)

Safe to Include

  • HTTP status codes and response times
  • Error message text
  • Node IDs and file keys (not secrets)
  • Rate limit header values

Resources

Next Steps

For rate limit issues, see figma-rate-limits.

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results