Figma Upgrade Migration

What it does

When your agent uses it

• Migrating from deprecated scopes
• Updating webhook versions
• Adapting to Figma API changelog changes
• With phrases like upgrade figma

Example prompts

• “upgrade figma”
• “figma deprecation”
• “figma scope migration”
• “/figma-upgrade-migration”

Requirements

• Compatibility (from SKILL.md): Designed for Claude Code
• Pre-approved tools (allowed-tools): Read, Write, Edit, Bash(npm:*), Bash(git:*)

Workflow steps

4 steps, taken from the step headings in SKILL.md.

1. 1Scope Migration (files:read Deprecation)
2. 2Webhooks V1 to V2 Migration
3. 3OAuth App Publishing Flow
4. 4Audit and Update Codebase

What it can do on your machine

Read from SKILL.md and the folder at commit cfae287. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Write
  • Edit
  • Bash(npm:*)
  • Bash(git:*)

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • curl
  • jq

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Hosts in commands or code, which the agent is likely to contact:

  • api.figma.com

  Also links to:

  • developers.figma.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Designed for Claude Code

  From compatibility in the SKILL.md frontmatter.

Context cost

Figma Upgrade Migration loads about 1.6k tokens when it runs, and up to ~3k if it reads all its reference files. Until then it costs about 85 tokens; SKILL.md has 347 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~85

When it runs · the whole SKILL.md, loaded when a task matches

~1.6k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jeremylongshore/tons-of-skills-marketplace at commit cfae287, republished under its MIT licence (© jeremylongshore). 347 words, ~1,635 tokens.

name

figma-upgrade-migration

description

Handle Figma REST API scope changes, deprecations, and migration tasks. Use when migrating from deprecated scopes, updating webhook versions, or adapting to Figma API changelog changes. Trigger with phrases like "upgrade figma", "figma deprecation", "figma scope migration", "figma API changes", "figma v2 webhooks".

allowed-tools

Read, Write, Edit, Bash(npm:*), Bash(git:*)

compatibility

Designed for Claude Code

version

1.6.0

license

MIT

author

Jeremy Longshore <jeremy@intentsolutions.io>

tags

saas, figma

# Find all Figma API calls in your codebase
grep -rn "api.figma.com" --include="*.ts" --include="*.js" src/ \
  | grep -oP '/v\d/[a-z_/]+' | sort -u

# Example output:
# /v1/files
# /v1/files/comments
# /v1/images
# /v2/webhooks

// V1 (deprecated): POST /v1/webhooks
// V2 (current):    POST /v2/webhooks

// V2 adds context support: attach webhooks to teams, files, or projects
interface WebhookV2Config {
  event_type: 'FILE_UPDATE' | 'FILE_DELETE' | 'FILE_VERSION_UPDATE'
    | 'FILE_COMMENT' | 'LIBRARY_PUBLISH';
  // Context: where to listen
  team_id?: string;      // team-level (all files in team)
  // OR specify project/file context in the endpoint path
  endpoint: string;      // Your HTTPS webhook URL
  passcode: string;      // Secret for verification
  description?: string;
}

// Create a V2 webhook
async function createWebhook(config: WebhookV2Config) {
  const res = await fetch('https://api.figma.com/v2/webhooks', {
    method: 'POST',
    headers: {
      'X-Figma-Token': process.env.FIGMA_PAT!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(config),
  });
  if (!res.ok) throw new Error(`Webhook creation failed: ${res.status}`);
  return res.json();
}

// List existing webhooks
async function listWebhooks(teamId: string) {
  const res = await fetch(
    `https://api.figma.com/v2/webhooks?team_id=${teamId}`,
    { headers: { 'X-Figma-Token': process.env.FIGMA_PAT! } }
  );
  return res.json();
}

// Check if your OAuth tokens need refresh
async function checkTokenHealth(accessToken: string): Promise<boolean> {
  const res = await fetch('https://api.figma.com/v1/me', {
    headers: { 'X-Figma-Token': accessToken },
  });
  if (res.status === 403) {
    console.warn('Token expired or revoked -- refresh needed');
    return false;
  }
  return res.ok;
}

// Create a migration checker
function auditFigmaIntegration(codebasePaths: string[]) {
  const issues: string[] = [];

  // Check for deprecated scope usage
  // Check for V1 webhook endpoints
  // Check for old token format
  const patterns = [
    { pattern: 'files:read', message: 'Deprecated scope: use file_content:read' },
    { pattern: '/v1/webhooks', message: 'V1 webhooks: migrate to /v2/webhooks' },
    { pattern: 'X-FIGMA-TOKEN', message: 'Header is case-sensitive: use X-Figma-Token' },
  ];

  return { issues, patterns };
}

/usr/bin/grep -rn "files:read" --include='*.{ts,js,json,yml}' . | /usr/bin/grep -v node_modules

src/auth/oauth.ts:12:  scope: 'files:read',        ← replace with file_content:read
config/figma-app.json:8: "scopes": ["files:read"]  ← update in the Figma app config too

curl -s -X POST https://api.figma.com/v2/webhooks \
  -H "X-Figma-Token: ${FIGMA_PAT}" -H 'Content-Type: application/json' \
  -d '{"event_type":"FILE_UPDATE","team_id":"'"${FIGMA_TEAM_ID}"'","endpoint":"https://example.com/figma/webhook","passcode":"'"${WEBHOOK_PASSCODE}"'"}' \
  | jq '{id, event_type, status}'

© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 5 other files (references) in skills/.curated/figma-upgrade-migration of jeremylongshore/tons-of-skills-marketplace.

• SKILL.md
• references/audit-and-update-codebase.md
• references/errors.md
• references/oauth-app-publishing-flow.md
• references/scope-migration-files-read-deprecation.md
• references/webhooks-v1-to-v2-migration.md

Open the folder on GitHubat commit cfae287