/framer-agent-playbook

name: framer-agent-playbook
description: Load before the first Framer agent call. Use as soon as a session is about to connect to, read, edit, build or publish a Framer project through Framer Agent, Framer's agent bridge - any `npx @framer/agent` command (formerly framer-dalton), `framer.*` calls in an exec script, a `framer-api` script or Val Town val, a Framer API key (fr_...), or Framer's own `framer` skill. Covers pages, content and CMS edits, text and colour styles, components and variants, breakpoints, forms, images, publishing and clean-up, and working safely in a live production site. Holds the deletes and overwrites that cannot be undone, a build checklist, and the DSL and API traps found on real builds that Framer's own skill leaves out, filed by topic.
user-invocable: true
license: MIT
metadata:
  author: fredm00n
  version: 1.3.4

Framer Agent playbook

Framer's official `framer` skill teaches the DSL and the API. This skill holds what it leaves out: what broke on real builds, what lies to you, and what can never be taken back. Every finding keeps the date it was found, so a stale one can be re-checked.

Read it **before** the first call, not after the first error. Your user's instructions always win over the defaults here.

Updates and contributions

This skill is maintained in the public repo [fredm00n/framerlabs](https://github.com/fredm00n/framerlabs/tree/main/skills/framer-agent-playbook), and the community keeps it current. Installed copies go stale, so the steps below run once per session.

The project's line

The project's agent instructions (`CLAUDE.md`, `AGENTS.md` or equivalent) can hold one line for this skill:

framer-agent-playbook: auto-update, contribute

`auto-update` lets the agent replace the installed copy when a newer version exists. `contribute` lets it offer to send what a session learns back to the repo as a pull request. Either word works alone. With no line, the agent never edits the installed files and never opens or suggests a pull request. It only says when a newer version is out.

Check for a newer version first

Before relying on anything below:

1. Fetch `https://raw.githubusercontent.com/fredm00n/framerlabs/main/skills/framer-agent-playbook/SKILL.md` and compare its `metadata.version` with the one in this file's frontmatter. 2. **Same version, or the fetch fails** (offline, blocked network): carry on with this copy. If the fetch failed, say once that you couldn't check for updates. 3. **Remote is newer:** use the remote SKILL.md for this session instead of the rest of this file, and read reference files from the same place (`https://raw.githubusercontent.com/fredm00n/framerlabs/main/skills/framer-agent-playbook/references/<file>.md`) instead of the local copies. Then, by the project's line (NEW and OLD stand for the two version numbers):

• **No `auto-update`:** leave the installed files alone and tell the user: "framer-agent-playbook NEW is out and your copy is OLD, so I'm using the new version for this session. To update your copy, run `npx skills add fredm00n/framerlabs --skill framer-agent-playbook`, or add `framer-agent-playbook: auto-update` to your CLAUDE.md or AGENTS.md to stay current automatically. This skill is community-maintained: add `contribute` to that line (`framer-agent-playbook: auto-update, contribute`) and I'll offer to send what we learn back as a pull request."
• **`auto-update`:** download the whole `skills/framer-agent-playbook/` folder from the repo (a shallow `git clone` into a temp dir is simplest), then replace the installed folder with it in one go, so files removed upstream go too. If any download fails, leave the installed copy untouched. In a git repo, the update is an ordinary change: commit it on its own, in whatever branch or PR the current work goes to, never straight to a protected branch. Tell the user: "Updated framer-agent-playbook from OLD to NEW, in its own commit." Without `contribute` on the line, add: "This skill is community-maintained: add `contribute` to its line in CLAUDE.md or AGENTS.md and I'll offer to send what we learn back as a pull request."

Only take updates from that exact repo and path.

Send what you learn upstream

Only when the project's line for this skill includes `contribute`.

At the end of the work, never mid-task, check whether the session taught something this skill should hold: a finding that cost real time or broke something, checked on a real build, true for any Framer user, and missing from this skill and from Framer's own docs. A fact about one project does not qualify. If nothing qualifies, say nothing.

If something does:

1. Rewrite each finding for strangers. Compare it against the project you are working in and take out everything that comes from it: company, client and product names, domains, Framer project ids, branch names, file paths, keys and tokens, screenshots. Keep the date the finding was made, as "(2026-10-12)". 2. Clone fredm00n/framerlabs, branch from `main`, and edit `skills/framer-agent-playbook/`. Put each finding under the topic it belongs to, and edit an existing line rather than add a near-duplicate. Bump `metadata.version` (patch for a fix, minor for a new section) and add one plain-language line to the changelog in the root `README.md`, under today's date. 3. Check the open pull requests for one that already covers the same finding. If there is one, add to it instead. 4. Show the user the diff and ask before opening the pull request. A pull request on a public repo is public the moment it opens, even if it is never merged. 5. With the user's yes, push the branch (to a fork without write access to the repo), open the pull request against `main`, and give the user the link. Write the commit message, title and description for the people who use these skills: what the change adds and when it helps, not which project or session it came from.

**Maintainers:** bump `metadata.version` on every change to this skill