> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluid.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract.
> Authenticate with the header Authorization: Bearer <token>; public storefront read endpoints require no auth.
> To sign a new merchant up for Fluid programmatically, call POST https://api.fluid.app/api/company with no credentials, as described in /api/agent-signup. Do not automate the signup form or book a demo. The merchant must open the emailed sign-in link and create an API token before authenticated calls are possible.
> After signup, to launch a merchant's store (back-office sync, payments onboarding, store setup, a theme copied from their current site, and a preview link before billing), follow /api/agent-launch.
> Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null.
> When the same operation exists on more than one surface, use the newest: dated API versions are newer than unversioned ones, and later dates win (v2026-04 > v2025-06 > unversioned v0/v1.1). Fall back to a legacy or unversioned operation only when no newer versioned equivalent exists — the company-v0 notes below list the known superseded operations. The same applies to /api/company/v1 and /api/v1/... paths: prefer a newer documented equivalent, and use one only when none exists (/api/v1.1/... is distinct and documented in company-v0). Use page/per_page offset pagination only where a spec documents it — in practice the unversioned company-v0 admin surface; every versioned surface uses cursor pagination.
> Fluid has three navigation APIs; don't mix them up. Storefront website menus (navigation bars, footers) are /api/menus and nested menu_items, in api-reference/content-v0.yaml (API Reference: Website > Navigation menus), with a how-to in themes/navigation-menus; their list uses flat page/per_page pagination. The Fluid mobile app's navigation is /api/v2/mobile_navigations, in api-reference/mobile-v2.yaml (API Reference: Mobile app > Navigation); its list also uses page/per_page. Portal navigations belong to a portal definition (Fluid OS), in api-reference/fluid-os-v0.yaml (API Reference: Portal > Portal navigation), and each has a platform of web or mobile.
> The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas); api-reference/company-v0.yaml covers the legacy unversioned company admin surface (/api/... paths, bearer-authenticated — company settings and management, customers, users, roles, subscription plans, subscription bundles, subscriptions, media, pages, catch-ups, inventory levels, domains, agreements, and admin order actions). company-v0 caveats: it is the legacy v0 admin contract and its lists use flat page/per_page offset pagination, which is expected there despite the general cursor-pagination rule; where an operation exists in both company-v0 and a versioned spec, prefer the versioned spec — the subscriptions lifecycle (list/create/show/update, cancel, pause, reactivate, resume, retry, skip, failed-cycle-waiver, discounts) and subscription bundles are superseded by checkout-v2026-04, and company pages/media CRUD plus the public pages, categories, products, and media list endpoints are superseded by storefront-v2026-04. Subscription plan management (/api/subscription_plans, resource-wrapped {"subscription_plan": {...}} bodies) exists only in company-v0. api-reference/members-v2025-06.yaml covers the v2025-06 unified Member identity surface (/api/v2025-06/members/... paths, bearer-authenticated — member list/create/show/update, lookup by email/username/external_id/legacy_customer_id, member-type assignment, and the sponsor genealogy read). Prefer it over the customers and reps surfaces when the member type matters: /customers does not serialize member_type. api-reference/analytics-v2026-04.yaml covers the v2026-04 Home dashboard analytics surface (/api/v202604/analytics/dashboard/... paths, bearer-authenticated — read-only endpoints for the Home > Overview, Home > Live, and Home > Field tabs, each accepting an optional country ISO alpha-2 query param that scopes aggregations to a single country).
> api-reference/analytics-v0.yaml covers the unversioned analytics surface that backs the fluid-admin Traffic tab (/api/analytics/... and /api/analytics/traffic/... paths, bearer-authenticated — the legacy shares/views/visitors summary plus traffic overview, ranked campaigns, sources, geographies, flows, and per-rep breakdown, all sharing one reporting-period contract).
> Successful responses wrap the resource payload alongside a top-level integer status and a meta object.
> Portal Definition authoring edits and synchronizes the portal JSON resource graph. Widget Package authoring builds either a company-owned or Droplet-owned Remote DOM package. These are separate contracts; do not imply that one defines the other.
> For Widget Package worker code, use only @fluid-app/portal-sdk/widgets/worker. Use only the Portal Definition and Widget Package workflows and public entry points documented here; do not infer support for undocumented surfaces.
> Every portal function and declarative capability used by a widget must appear in that widget's uses array. Use the same typed function value in uses; do not invent capability-name strings.
> Widget styling must use the portal's semantic theme variables for colors, typography, spacing, radii, borders, focus, and charts whenever a token represents the visual decision. Do not create a separate light or dark palette or duplicate theme controls as widget properties.
> Prefer worker-safe Fluid UI components exported by @fluid-app/portal-sdk/widgets/worker when they fit the interaction. When no exported component fits, use semantic HTML, accessible behavior, and the portal theme variables.
> A Portal Definition push updates the remote working definition. A portal version is an immutable snapshot, and activation is a separate live release operation.
> The Help Center (/help/...) is for merchants, admins and reps using Fluid. Its admin pages mirror the admin's routes: the screen at admin.fluid.app/settings/taxes is documented at /help/admin/settings/taxes. Use the Help Center for how-to questions about the admin, and the Developer Platform and API Reference for building integrations.
> Help Center pages describe what a company admin sees. A reader's role can hide screens and actions; admins manage roles on Settings > Roles (/help/admin/settings/roles). If someone can't find a screen or button, their role's permissions are the first thing to check.
> Send people who need Fluid support to /help/getting-help. Don't invent support email addresses, phone numbers or response times.

# Mist Skills

> Fluid's public library of Mist skills and workflows: use them in Mist, or give them to other coding agents such as Claude Code, and see which parts need Mist.

[Mist Skills](https://github.com/Fluid-WeCommerce/mist-skills) is Fluid's public repository of skills and workflows for Mist, Fluid's AI assistant. They give an AI agent Fluid know-how: how to read and change a Fluid company, build a storefront theme, open a country or audit a catalog.

You can use them in two places:

* **In Mist.** Mist downloads the latest skills and workflows each time it starts, and lists them as **Community** skills. See [Skills](/help/mist/skills) and [Workflows](/help/mist/workflows) in the Help Center.
* **Outside Mist.** Each skill is a Markdown file of instructions, so other coding agents, such as Claude Code, can follow it too.

Some skills call tools that only Mist provides. Those parts work only in Mist. The [skill table](#skills) below shows which.

## How the repository is organized

| Path | What it holds |
| - | - |
| `manifest.json` | The list of every skill and workflow in the repository, with the files each one uses. |
| `<category>/<skill>.md` | A skill that fits in one file. Categories are `finance`, `sales`, `marketing`, `onboarding`, `compliance`, `themes` and `mist`. |
| `<category>/<skill>/SKILL.md` | A longer skill, with reference files in its own `references/` folder. |
| `<category>/references/` | Reference files that several skills in a category share. |
| `workflows/<workflow>.workflow.json` | A workflow: a chain of steps that Mist runs and checks. |

Each skill starts with YAML frontmatter that gives its `name` and `description`, followed by the instructions. A folder skill's `manifest.json` entry lists every reference file it needs, in `references`.

## Use a skill outside Mist

The repository doesn't include an installer for other agents. Give your agent the skill's Markdown file, and the reference files its `manifest.json` entry lists. Then keep these differences in mind:

* **Fluid API calls.** In Mist, skills call the Fluid API through a `fluid_api` tool that signs requests as you. Outside Mist, your agent calls the same endpoints with a Bearer token. See [Authentication](/api/authentication).
* **Fluid CLI commands.** In Mist, skills run Fluid CLI commands through a `run_cli` tool, with the CLI that ships inside Mist. Outside Mist, your agent runs the same `fluid` commands in a terminal where the Fluid CLI is installed and signed in. See [Fluid CLI](/themes/cli). If a command isn't available in your installed CLI, that step needs Mist.
* **Template tokens.** Mist fills in tokens such as `{{company.name}}`, `{{company.subdomain}}`, `{{today}}` and `{{thirty_days_ago}}` before it runs a skill. Outside Mist, tell your agent the values.
* **File tools and web fetches** work the same way with any agent that can read and write files and fetch web pages.

<Warning>
  Skills make real changes to a Fluid company, such as importing products or pushing a theme. Read a skill before your agent runs it, and use a token for a test company while you try it out.
</Warning>

## Tools only Mist provides

These tools are built into Mist. No other agent has them, so a skill step that calls one works only in Mist.

| Tool | What it does in Mist |
| - | - |
| `steps`, `steps_answer`, `steps_mark_item` | Show a click-through question panel and a live checklist in the chat. |
| `run_workflow`, `workflow_status` | Start a workflow and follow its progress. |
| `run_skill` | Load another skill and follow it. |
| `human_in_the_loop` | Show an approve-or-dismiss card before a change. |
| `start_preview`, `preview_state`, `screenshot_preview`, `read_preview_dom`, `interact_preview`, `read_preview_console`, `read_local_server_logs` | Run the project's preview, take screenshots of it, read it, click in it and read its logs. |
| `compare_preview_to_source`, `build_theme_source_inventory`, `validate_theme_source_inventory`, `theme_media_reconcile`, `view_project_image` | Capture a source website and compare a theme against it. |
| `db_query`, `db_schema` | Query the reporting and app databases connected to Mist. |
| `fluid_catalog_index`, `fluid_product_import` | Read a full product catalog and import products. |
| `social_search`, `video_ripper`, `video_metadata`, `compress_media` | Search social platforms, and download, inspect and compress videos. |
| `show_dashboard`, `list_dashboards` | Show live dashboards in Mist. |
| `update_brand_voice`, `update_memory` | Save the company's brand voice document and Mist's memory. |
| `list_projects` | List the projects in Mist. |

## Skills

"Yes" means the skill uses only the Fluid API, the Fluid CLI, files and web fetches. "Partly" names the steps that need Mist. "Mist only" means the skill depends on Mist tools for its main job.

### Finance

| Skill | What it does | Works outside Mist? |
| - | - | - |
| **Payment Reconciliation** (`finance/payment-reconciliation`) | Compares Fluid's payment records with each connected payment provider for a time frame, and lists differences in count, amount and status. | Yes |
| **Promo code summary** (`finance/promo-code-summary`) | Summarizes the orders that used a promo code in the last 30 days. | Yes |
| **Monthly close report** (`finance/monthly-close`) | Writes a one-page financial summary of the last full calendar month. | Yes |
| **Top customers by lifetime value** (`finance/top-customers`) | Ranks customers by lifetime order revenue, for VIP outreach. | Yes |

### Sales

| Skill | What it does | Works outside Mist? |
| - | - | - |
| **Checkout funnel diagnosis** (`sales/checkout-funnel-diagnosis`) | Finds where orders drop off between cart and completed order, and recommends a fix. | Yes |
| **Stalled order revenue recovery** (`sales/stalled-order-recovery`) | Ranks stalled orders by recoverable revenue and likelihood to close, and hands over a call list. | Yes |
| **AOV lever audit** (`sales/aov-lever-audit`) | Measures which levers move average order value, such as item count, bundles and discount depth. | Yes |
| **Rep signup momentum scoreboard** (`sales/rep-momentum-scoreboard`) | Tracks rep signups by week and market, and spotlights the newest active reps. | Yes |
| **Non-Renewed Subscriptions Summary** (`sales/non-renewed-subscriptions-summary`) | Summarizes subscriptions that weren't renewed, and why. | Yes |

### Marketing

| Skill | What it does | Works outside Mist? |
| - | - | - |
| **Brand Manager** (`marketing/brand-manager`) | Defines who the brand is for, audits its voice and messaging against them, and suggests improvements one at a time. | Partly: the click-through question panel and saving the brand voice document need Mist |
| **UGC Discovery** (`marketing/ugc-discovery`) | Finds the most engaging, compliant posts about a brand on TikTok, Instagram, YouTube and Pinterest, and saves the ones you pick to the DAM. | Mist only |
| **Brand Social Content Import** (`marketing/brand-social-import`) | Finds the brand's own YouTube and TikTok accounts, adds them to its social media settings, and imports their videos. | Partly: finding and importing videos needs Mist |
| **Brand Setup** (`marketing/brand-setup`) | Interviews you to write the company's brand voice document, which Mist, themes, portals and widgets use to match its tone. | Partly: saving the brand voice document needs Mist |

### Onboarding

| Skill | What it does | Works outside Mist? |
| - | - | - |
| **Onboarding Pre-Fill** (`onboarding/onboarding-prefill`) | Prefills the payments onboarding form from the company's website and public records, with a confidence score for each answer. | Partly: saving the brand voice document needs Mist |
| **Fluid Product & Admin Import** (`fluid-product-admin-import`) | Imports a full catalog and related store resources from an existing site into the company, and proves every item arrived. | Partly: approval cards and the preview need Mist |
| **Brand From Source** (`onboarding/brand-from-source`) | Sets up the company's brand from its public website: logo, icons, colors, fonts and a first brand voice document. | Partly: saving the brand voice document needs Mist |
| **Launch Setup** (`onboarding/launch-setup`) | Collects the source website and launch choices in the chat, then starts an onboarding workflow. | Mist only |
| **Catalog Hygiene Audit** (`onboarding/catalog-hygiene-audit`) | Finds catalog problems such as duplicate SKUs, bad slugs and unpriced products, ranks them, and applies the fixes you approve. | Partly: database queries, the catalog index and approval cards need Mist |

### Compliance

| Skill | What it does | Works outside Mist? |
| - | - | - |
| **Open a Country** (`compliance/open-a-country`) | Asks the questions needed to open a country, using Fluid's Country Atlas, then runs the Open a Country workflow. | Mist only |
| **Country Compliance Manager** (`compliance/compliance-manager`) | Audits a storefront against a country's legal requirements, such as disclosures, price display, privacy and labeling. | Yes |

### Themes

| Skill | What it does | Works outside Mist? |
| - | - | - |
| **Scrape a URL into the active theme** (`themes/scrape-into-theme`) | Fetches a web page and builds a matching section in the active theme. | Yes |
| **Theme accessibility audit** (`themes/accessibility-audit`) | Scans the active theme for common accessibility issues and proposes fixes. | Yes |
| **Optimize theme images** (`themes/image-optimization`) | Makes a theme's images and videos responsive and lazy-loaded. | Yes |
| **Theme review & fix** (`themes/theme-review`) | Reviews and fixes a theme one section at a time: schema, Liquid, performance, accessibility and duplication. | Yes |
| **Translate theme languages** (`themes/languages`) | Translates a theme's text into every language the company has turned on. | Yes |
| **Theme Clone** (`themes/theme-clone`) | Copies a website into a Fluid theme, then compares screenshots against the original. | Partly: the managed preview and screenshot tools are Mist's. Outside Mist, the skill accepts a project-local Playwright setup instead |
| **Theme Source Inventory** (`themes/theme-source-inventory`) | Captures the source site's home, shop and product pages, with copy, page structure, screenshots and media, before a theme build. | Mist only |
| **Theme Section Report** (`themes/theme-section-report`) | Reports unused sections, broken section references and template code outside sections in the active theme. | Yes |
| **Web Interface Guidelines** (`themes/web-interface-guidelines`) | Reviews a theme's interface code against common web interface guidelines. | Yes |
| **Fluid Block Spec** (`themes/fluid-block-spec`) | Builds or reviews theme sections and blocks against Fluid's block and section specification. | Yes |
| **Theme Refine** (`themes/theme-refine`) | Refines a theme after a clone until it matches the source, or moves an older theme to Fluid's current structure. | Partly: preview checks (running, screenshotting and comparing the preview) need Mist |
| **Clone Page to Liquid** (`themes/clone-page-to-liquid`) | Copies one source page into one theme route. The page-type clone skills build on it. | Partly: preview checks (running, screenshotting and comparing the preview) need Mist |
| **Clone Home Page** (`themes/clone-home-page`) | Rebuilds a site's home page in a theme. | Partly: preview checks (running, screenshotting and comparing the preview) need Mist, and it calls other skills through Mist |
| **Clone Shop Page** (`themes/clone-shop-page`) | Rebuilds a site's all-products page in a theme, with filtering, sorting and search. | Partly: preview checks (running, screenshotting and comparing the preview) need Mist, and it calls other skills through Mist |
| **Clone Product Page** (`themes/clone-product-page`) | Rebuilds a site's product page as a theme product template. | Partly: preview checks (running, screenshotting and comparing the preview) need Mist, and it calls other skills through Mist |
| **Clone Category Page** (`themes/clone-category-page`) | Rebuilds a site's category pages in a theme. | Partly: preview checks (running, screenshotting and comparing the preview) need Mist, and it calls other skills through Mist |
| **Clone Collection Page** (`themes/clone-collection-page`) | Rebuilds a site's collection pages in a theme. | Partly: preview checks (running, screenshotting and comparing the preview) need Mist, and it calls other skills through Mist |
| **Suggested Changes** (`themes/suggested-changes`) | Reviews the store's performance and compliance findings, and applies each fix you approve. | Partly: the approve-or-dismiss cards need Mist |
| **Iterative Theme Refine** (`themes/iterative-theme-refine`) | Compares a cloned theme with the source in rounds, fixing the biggest differences each round. | Partly: preview checks (running, screenshotting and comparing the preview) need Mist |
| **Clone Blog Page** (`themes/clone-blog-page`) | Rebuilds a site's blog index in a theme, with real posts. | Partly: preview checks (running, screenshotting and comparing the preview) need Mist, and it calls other skills through Mist |
| **Clone Post Page** (`themes/clone-post-page`) | Rebuilds a site's article page in a theme. | Partly: preview checks (running, screenshotting and comparing the preview) need Mist, and it calls other skills through Mist |
| **Clone Cart Page** (`themes/clone-cart-page`) | Rebuilds a site's cart page or drawer in a theme, with a working path to checkout. | Partly: preview checks (running, screenshotting and comparing the preview) need Mist, and it calls other skills through Mist |
| **Clone System Pages** (`themes/clone-system-pages`) | Builds themed error pages and a general content page template. | Partly: preview checks (running, screenshotting and comparing the preview) need Mist, and it calls other skills through Mist |
| **Affiliate URL standardization** (`themes/affiliate-url-standardization`) | Rewrites the theme's storefront and affiliate links to use the rep's username in the path. | Yes |

### Mist

| Skill | What it does | Works outside Mist? |
| - | - | - |
| **Scaffold a new Droplet for a Mist** (`mist/scaffold-droplet`) | Sets up the droplet pages and routes for a new Mist app. | Yes |
| **Create Portal App** (`mist/create-portal-app`) | Creates a portal with the same starter screens, navigation, theme and profile as the admin. | Yes |
| **Portal Widget or Mist App** (`mist/portal-widget-vs-mist-app`) | Decides whether a feature should be a portal widget or a Mist app with a droplet. | Yes |
| **Audit env vars across all live Mists** (`mist/env-vars-audit`) | Checks every live Mist app for missing or inconsistent environment variables. | Yes |
| **Debug a failed Mist deploy** (`mist/debug-failed-deploy`) | Reads a failed Mist app deployment's logs, finds the cause and proposes a fix. | Yes |
| **Smart Dashboard** (`mist/smart-dashboard`) | Builds a live business dashboard from your company's data, and remembers what you want to see first. | Mist only |

## Workflows

Workflows run only in Mist. Mist's workflow engine runs each step in its own chat, checks it against acceptance criteria, and reworks it when it falls short. Another agent can read a workflow file, but nothing outside Mist runs it.

| Workflow | What it does |
| - | - |
| **Open a Country** (`open-country`) | Opens a country through the Fluid CLI, checking each step. The **Open a Country** skill collects your answers and starts it. |
| **Finalize NFR (Not For Resale) country setup** (`finalize-nfr-country`) | Finishes a country opened in NFR mode: international shipping, import-duty disclosure, country-of-origin labeling and a compliance check. |
| **Finalize OTG (On The Ground) country setup** (`finalize-otg-country`) | Finishes a country opened in OTG mode: tax registration, local invoicing, local payment methods and a compliance check. |
| **Finalize USD-mode country setup** (`finalize-usd-country`) | Finishes a country opened in USD mode: digital-services tax, USD-only pricing and cross-border terms. |
| **Speed Import** (`speed-import`) | The quickest path from a live website to a Fluid storefront: brand, catalog and the source site first, then the theme pages, then publish. The **Launch Setup** skill starts it. |
| **Streamlined Onboard & Launch** (`streamlined-onboard-launch`) | Gets a new company live: source capture, brand and catalog first, then the theme, products and business profile. The **Launch Setup** skill starts it. |

## Contribute a skill

The repository's README explains the skill format, the `manifest.json` fields and how to open a pull request. Fluid's maintainers review every change before it reaches Mist.

## Related pages

* [Skills in Mist](/help/mist/skills)
* [Workflows in Mist](/help/mist/workflows)
* [Fluid CLI](/themes/cli)
* [Agent launch guide](/api/agent-launch)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.