build-with-fillo20.7 KB
View saved version →
---
name: build-with-fillo
description: Create hosted Fillo forms or build, embed, style, sync, and verify product-native Fillo forms in React, Next.js, Vue, Svelte, Astro, or browser apps. Use when a task mentions Fillo, @usefillo packages, a Fillo form id or slug, a Build with AI handoff, a publishable key, form schema authoring, prefill, uploads, respondents, webhooks, integrations, or troubleshooting a Fillo form. Do not use for contributing to the Fillo monorepo itself.
---
# Build with Fillo
Add a real form inside the host product, or create a hosted Fillo link when the
user explicitly asks for a standalone, shareable form. For an embed, keep the
host app in control of its route, layout, components, account context, and
post-submit behavior. Let Fillo own schema, validation, uploads, responses,
versions, exports, and delivery.
Use the repository, browser, and test tools available in the current agent.
Never require a provider-specific agent command.
Use the installed version of this skill for the task. Run CLI commands only
for the user's requested Fillo work, without a startup update or fetching
replacement skill instructions. Respect pinned tooling, `FILLO_AUTO_UPDATE=0`,
project dependency constraints, and the host package manager's lockfile.
Set `FILLO_AUTO_UPDATE=0` in the environment of every CLI invocation under this
skill, except when the user explicitly requests a tooling or skill update. This
keeps CLI-managed skill files and references stable throughout the task.
When the user requests a skill update, use the host's plugin updater for
plugin-managed installs or the CLI skill installer for CLI-managed installs.
## Work in this order
1. On a first-time setup — installing Fillo or provisioning a workspace — open
with a three-line plan before running anything, for example: "1) I install
Fillo's SDK and skill. 2) I build the form inside your app. 3) You get an
email to claim your workspace, where responses live." Add that a few
permission prompts may need approving along the way. Then, if their work
email is not already in this task, ask them for it once. Do not invent an
address, infer or scrape it, or use a documentation placeholder as the
address. Run `npx @usefillo/cli@latest agent bootstrap --email <their email>`
with the address they give you. Skip the recap and the email ask when Fillo
is already set up in the repo or a handoff already supplied a workspace.
2. Inspect the task environment and any host repository. For an embed, identify
its framework, package manager, target route, existing Fillo packages, theme
provider/switch, light and dark selectors, CSS `color-scheme`, design tokens,
and the input, label, button, error, focus, spacing, radius, and typography
primitives already used beside the form. For a standalone hosted form, a
host route and renderer may not exist. In either path, preserve any supplied
form id, key, setup command, or run token.
3. If the form may need uploads, check storage readiness before choosing the
schema, not after a blocked publish. The `canPublishFileFields` boolean
answers whether an unpinned `storage = null` file field can publish now; it
does not confirm a specifically pinned provider. A provider can also show
connected while no default destination is resolved. With a CLI login, read
the generic signal and provider-specific status from `fillo whoami` or
`fillo storage status` (both `--json`). On the unclaimed preview (no login),
those commands are unreachable — read the generic signal from `agent
bootstrap` or `push --json`, and treat an exact durable selection as pending
until the owner connects it. Do not defensively drop a needed file field;
ask the user to finish connecting its destination instead.
4. Establish the form's source of truth:
- Published form id or slug: render it directly. No client key is required.
- React-owned schema: use `<Fillo.Form>` or `defineForm()` with
`@uPreview of the first 4,000 characters. Read full instructions →
Referenced files: 8 — file references are metadata, not package contents.