agentleFS
southleftsouthleft/figma-console-mcp-skills/skills/figma-version-history/SKILL.md

figma-version-history

Skill83 starsChanged 6 months agoMITView on GitHub

List a Figma file's version history, snapshot the file at any past version, and diff two versions (added/removed/renamed pages plus deep per-component changes). Use when the user wants to inspect Figma history — triggers: 'list Figma versions', 'what versions does this file have', 'show version history', 'snapshot this file at version X', 'get the file as it was last week', 'diff two Figma versions', 'what changed between these versions', 'compare version A and B', 'did this component change between releases'. Uses the Figma REST API + a personal access token because version history is NOT reachable via the Plugin API / use_figma / the native Figma MCP. For a prose release-notes writeup use figma-generate-changelog; to find which version introduced a change use figma-blame-node.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All requests go to https://api.figma.com with the header X-Figma-Token: $FIGMA_TOKEN.

    line 21
  2. Very specific:

    Use current (or omit --to) to diff against HEAD.

    line 80

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

figma-version-history — list, snapshot & diff Figma versions

Version history lives only in Figma's REST API, so this skill calls REST directly with a personal access token (PAT). It does three things:

  1. List a file's version history (label, description, author, timestamp, version id).
  2. Snapshot the file (or just some nodes) as it existed at a given version_id.
  3. Diff two versions — a cheap page-structure diff always, plus optional deep per-component diffs at depth=2.

Setup — terminal + token required. This skill runs shell commands, so it works in Claude Code (including the "Code" tab inside Claude Desktop), Cursor, Codex, or Gemini CLI — it does not run in plain Claude Desktop or claude.ai chat (no shell). The Figma connector's OAuth login does not authorize these REST calls, so you must supply your own Figma personal access token: in Figma go to Settings → Security → Personal access tokens, generate one with scope File content: read (plus File versions: read), then set it in your shell: export FIGMA_TOKEN="figd_…". The script reads it from the environment at runtime — never put the token in a skill file.

Setup & skill boundaries

  • All requests go to https://api.figma.com with the header X-Figma-Token: $FIGMA_TOKEN.
  • Endpoint reference: references/endpoints.md.

Derive the file key

The file key is the path segment after /design/ or /file/ in a Figma URL:

FILE_URL="https://www.figma.com/design/ABC123def456/My-File"
FILE_KEY=$(echo "$FILE_URL" | sed -E 's#.*/(design|file)/([A-Za-z0-9]+).*#\2#')
echo "$FILE_KEY"   # ABC123def456

Workflow

  1. List versions to find the version_ids you care about. Run scripts/list-versions.sh:

    ./scripts/list-versions.sh ABC123def456              # labeled versions only (default)
    ./scripts/list-versions.sh ABC123def456 --autosaves  # include unlabeled auto-saves

    It auto-paginates (newest-first) and prints version_id | created_at | author | label. By default it filters out unlabeled auto-saves; pass --autosaves to keep them.

  2. Snapshot a version with a one-line curl (omit &version= for current/HEAD). Save to disk so you can diff repeatedly without re-fetching — past versions are immutable:

    # Whole file at a past version (depth=1 keeps it small for orienting)
    curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
      "https://api.figma.com/v1/files/$FILE_KEY?version=4096761871&depth=1" \
      > /tmp/v-4096761871.json
    
    # Just specific nodes at that version (much smaller payload)
    curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
      "https://api.figma.com/v1/files/$FILE_KEY/nodes?ids=695:313&version=4096761871&depth=2"
    
    # Current / HEAD — omit the version param entirely
    curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
      "https://api.figma.com/v1/files/$FILE_KEY?depth=1"
  3. Diff two versions with scripts/diff-versions.mjs. It fetches both snapshots, computes a page-structure diff (cheap, 2 calls), and — if you pass --components — deep per-node diffs at depth 2 (added/removed children, name/description changes, componentPropertyDefinitions changes for COMPONENT_SETs, and boundVariables deltas):

    # Page-structure diff only (2 API calls)
    node scripts/diff-versions.mjs --file ABC123def456 --from 4096761871 --to current
    
    # Deep diff of specific component sets (2 calls per node), detailed verbosity
    node scripts/diff-versions.mjs --file ABC123def456 --from 4096761871 --to 4096800000 \
      --components 695:313,420:88 --mode detailed

    Use current (or omit --to) to diff against HEAD. --mode is summary (counts only), standard (names + counts, default), or detailed (full property/binding detail).

What the diff DOES and does NOT track

The diff is honest about its blind spots — don't read "no changes" as "nothing changed":

  • Tracks: page structure (added/removed/renamed pages); on scoped nodes — children added/removed, componentPropertyDefinitions (added/removed/type/default change), name & description changes, and variable binding references.
  • Does NOT track: instances of components placed elsewhere on the canvas (only the nodes you pass as --components), raw layout props (hug-vs-fill, unbound paddings/widths/cornerRadius), unbound fills/strokes/effects, variable VALUE changes (Figma REST never exposes these), and style content. For forensic per-edit history including raw property changes, the live Desktop Bridge plugin's figma_get_design_changes is the complementary tool.

Notes

  • Figma's version pagination is cursor-style: after=<version_id> returns versions older in time (the list is newest-first). list-versions.sh handles this for you.
  • Old version_ids can be pruned by Figma's plan-tier retention policy — a 404 on snapshot usually means the version aged out, not that your key is wrong. Re-list to get valid IDs.
  • 403 on these endpoints means your PAT is missing the File versions: Read scope — reissue it.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.