flowy

Delegate Webflow work to Claude and have it land correctly. flowy turns Claude Code into a competent operator on your connected Webflow project: hand it a task — convert static pages to a CMS collection, componentize a section, audit a site, rebrand a template — and it does the work directly through the Webflow MCP, picks the right tool for each step, verifies its own writes, and never publishes or deletes without asking you first.

The hard part is not driving Webflow's tools; it is that agents get Webflow wrong in specific, expensive ways: they rebuild components the clipboard would have carried losslessly, report style writes that never landed, "fix" CMS bindings that were already working, and flatten interactive components because the Designer canvas cannot run script. flowy is the accumulated correction of those failures, from production client work. Every claim in it carries a date and traces back to the session that produced it.

Quick start

Four steps, all in Claude Code.

1. Connect the Webflow MCP server. This is what links Claude to your actual Webflow project. Skip if you already have it.

claude mcp add --transport http webflow https://mcp.webflow.com/mcp

Start claude, run /mcp, select the webflow server: your browser opens Webflow's login page, where you authorize the specific sites Claude is allowed to touch. Full details in Webflow's guide.

Working across several client workspaces? Register one server per workspace, project-scoped, and each keeps its own auth (claude mcp add --transport http <client-name> https://mcp.webflow.com/mcp -s project in that client's config-only folder). Verify the isolation the flowy way: ask for a site list from inside the folder; the answer should contain that workspace and nothing else. Any server name works; flowy's guards match every MCP server with "webflow" in its name, which is exactly what multi-workspace naming produces.

2. Install flowy. Pulls the plugin straight from this repository:

/plugin marketplace add yaroshidi/flowy
/plugin install flowy

3. Restart Claude Code and run /flowy:doctor. Do this before real work, every install. It verifies the Webflow MCP is connected, the guard hooks actually fire, and Python 3 is present to run them — the difference between protection and the appearance of protection. Fix what it reports.

4. Give it a task on a site you authorized:

"Audit the site: broken links, missing alt text, classes that exist but style nothing."

"Convert the three static team pages into a CMS collection and bind the template."

"Match the pricing cards' spacing and type scale to the hero section."

Nothing else to invoke. The skills activate themselves as Claude works; the guards sit underneath whether the model cooperates or not.

Optional: the Claude in Chrome extension gives Claude a second hand, the real Designer, for visual judgment and the Interactions panel. Without it flowy still does structure, CMS and audits, and says plainly which routes are closed. /flowy:setup exists for when a default is wrong for you, most commonly the browser.

Cursor, Codex, Windsurf, and other agents

Via skills.sh:

npx skills add yaroshidi/flowy

The skills travel everywhere; the guard hooks and the two commands are Claude Code plugin machinery. On other agents you get the knowledge without the enforcement.

claude.ai, Claude Cowork, and the Claude API

These surfaces take one skill per upload, so the three skills ship merged into a single bundle — download flowy.zip from the latest release, or build it from a clone:

python3 scripts/build-universal.py     # -> dist/flowy.zip, dist/flowy.md

• claude.ai → Settings → Capabilities → Skills → upload flowy.zip. Skills uploaded to claude.ai appear in Cowork automatically (shared library).
• Claude API → upload the same zip to /v1/skills and attach it to Messages API or Agent SDK requests.
• Any other LLM → dist/flowy.md is the whole corpus as one flat file, for tools that can only take a pasted or attached document.

The merged skill carries a Running as a standalone skill section: with no guard hooks, the never-publish, never-resize, and confirm-irreversible-ops rules bind as instructions, and the verify checklist must be run at every batch boundary without a hook to prompt it.

From a local clone

git clone https://github.com/yaroshidi/flowy

Then in Claude Code: /plugin marketplace add ./flowy and /plugin install flowy.

Skills

Commands

Guard hooks

These run whether the model cooperates or not; everything else is documentation.

Two design decisions behind them. The guards fail safe: if a hook cannot parse its payload, it falls back to a substring check and asks. A false prompt costs a keystroke; a false pass costs a client site published without permission. And the destructive guard quotes the Webflow MCP schema itself: every operation it covers is one the schema documents as unrecoverable, each followed by "confirm with the user". Nothing made that confirmation happen; an agent mid-task reads its own intent as consent. The hook turns the instruction into a mechanism.

What flowy actually does

Routes work to the right hand. Webflow gives you three ways to change a site, and choosing wrong is most of the wasted time:

Verifies every write. Webflow MCP write responses report success on writes that did not land. A post-write hook prompts a structured re-read at each batch boundary.

Reads a project before touching it. flowy detects which convention a site already uses and adopts it. Imposing your naming system on a project that already has one is treated as a defect.

The verified-only rule

Every entry in flowy-manual references a directly observed event and the tool that produced it. No hedged language and no untested fixes; if something was seen once, the entry says it was seen once.

Reversals are struck and dated in place. When Webflow fixes something the old row stays, marked superseded <date> with a pointer to the new finding, because a verified-only ledger is only trustworthy if you can see where it was wrong. Every entry is anonymised: no client names, no site identifiers.

On currency: mcp-2.0.md is verified against Webflow MCP 2.0.1 and is the authority. mcp-capabilities.md is the historical ledger from May–July 2026 and is partly superseded. It is kept because the evidence is still the evidence; read mcp-2.0.md first and let it win.

What flowy does not do

Stated because a skill that claims everything is useful for nothing.

It does not publish. Ever, on its own. That is the point. It does not verify runtime behaviour of embedded scripts: embed <script> and <style> never execute on the Designer canvas, so flowy reports embed runtime as unchecked until a publish and treats that as a completed state. It does not replace the Designer; several things are Designer-only (clamp()/min()/max() and dvw/dvh values, descendant selectors, collection deletion) and flowy routes you there. It does not know your site; every session re-reads, because site IDs go stale and people edit between sessions. And it is not a Webflow tutorial. It assumes you know Webflow and is aimed at the failure modes of an agent driving it.

Configuration

Settings live at ~/.claude/flowy.config.md, in your home directory, so they survive plugin updates. Four values, all optional:

The publish gate, resize ban and verified-only reporting are not configurable.

Verifying the install

python3 scripts/validate.py

67 checks: manifests parse, hook matchers fire for any Webflow MCP server name, skill frontmatter meets spec, every relative link resolves, no orphaned files, hooks compile, and each guard returns the correct decision for representative payloads, including the malformed-input paths where failing safe matters most. The same script runs as CI on every push and pull request. /flowy:doctor covers what a static check cannot: that the plugin loads, the MCP servers are connected, and the hooks fire in a live session.

Contributing

Findings welcome, at the bar the manual holds itself to: name the tool call and the data point. A PR saying "this seems to happen" won't land. One saying "update_style with breakpoint_id:"main" returned status:"success" and query_styles read back the old value, 2026-06-01, ~6 calls on the same style across tab foreground and background" will.

The full bar (finding format, reversal policy, what gets merged and when) is in CONTRIBUTING.md. Merges happen in batches; this repo is maintained in bursts around client work, which is also where its findings come from.

Resources

• Webflow MCP documentation: the server flowy drives
• webflow/webflow-skills: Webflow's official agent skills. flowy complements them with hand-routing, hook-enforced guards, and observed-behaviour documentation
• skills.sh: cross-agent skill installs
• Client-First by Finsweet, Lumos by Timothy Ricks, and MAST by No-Code Supply Co: the three conventions flowy recognises and follows. flowy describes how to work inside each; it does not reproduce their documentation

Credits

Built by Yar Rosh from production Webflow client work. For project inquiries, get in touch.

License

MIT, see LICENSE.