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.
In this repository22 other files it gives its agents.
- figjam-create-contentSkill
- figma-analyze-component-setSkill
- figma-annotationsSkill
- figma-arrange-component-setSkill
- figma-audit-accessibilitySkill
- figma-blame-nodeSkill
- figma-check-design-paritySkill
- figma-commentsSkill
- figma-component-propertiesSkill
- figma-deep-componentSkill
- figma-design-system-inventorySkill
- figma-export-tokensSkill
- figma-extract-design-systemSkill
- figma-generate-changelogSkill
- figma-generate-component-docSkill
- figma-import-tokensSkill
- figma-library-variablesSkill
- figma-lint-designSkill
- figma-manage-variablesSkill
- figma-scan-code-accessibilitySkill
- figma-setup-design-tokensSkill
- figma-slidesSkill
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
- Very specific: line 21
All requests go to https://api.figma.com with the header X-Figma-Token: $FIGMA_TOKEN.
- Very specific: line 80
Use current (or omit --to) to diff against HEAD.
≈ “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.
Files
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:
- List a file's version history (label, description, author, timestamp, version id).
- Snapshot the file (or just some nodes) as it existed at a given
version_id. - 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.comwith the headerX-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" # ABC123def456Workflow
List versions to find the
version_ids you care about. Runscripts/list-versions.sh:./scripts/list-versions.sh ABC123def456 # labeled versions only (default) ./scripts/list-versions.sh ABC123def456 --autosaves # include unlabeled auto-savesIt auto-paginates (newest-first) and prints
version_id | created_at | author | label. By default it filters out unlabeled auto-saves; pass--autosavesto keep them.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"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,componentPropertyDefinitionschanges for COMPONENT_SETs, andboundVariablesdeltas):# 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 detailedUse
current(or omit--to) to diff against HEAD.--modeissummary(counts only),standard(names + counts, default), ordetailed(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'sfigma_get_design_changesis 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.shhandles this for you. - Old
version_ids can be pruned by Figma's plan-tier retention policy — a404on snapshot usually means the version aged out, not that your key is wrong. Re-list to get valid IDs. 403on these endpoints means your PAT is missing the File versions: Read scope — reissue it.
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
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.

