Set up with a coding agent

Faustine publishes three agent skills that install a Web Agent in your app and keep it in step with your code. Your coding agent (Claude Code, Cursor or Codex) reads the skill and edits your repository while you review the changes. The skills run on your machine only.

Before you begin

A Web Agent in your workspace whose analysis has finished. See Quickstart: add an agent to your web app.
A coding agent with access to the repository of your app.
Node.js, to run npx.

Install the skills

Run this in the directory of your app, the one with its package.json:

terminal

npx skills add faustine-ai/skills

The command adds the three skills for the coding agents you use. To add one skill only, name it:

terminal

npx skills add faustine-ai/skills --skill install-faustine

The skills are in the public repository faustine-ai/skills. Each one is a folder with a SKILL.md file. Without the skills CLI, copy the folder you need into your agent's skills directory. For Claude Code that is .claude/skills/.

Skill	Use it to	Arguments
`install-faustine`	Add the Web Agent to a Next.js app (App Router or Pages Router) or to a single-page app in React, Vue, Angular or Svelte.	`[agent id] [--setup <code>] [--env <name>] [--debug]`
`enable-faustine-adapter`	Add the Faustine adapter to a Next.js App Router app, so the agent can call Server Actions and server-only data functions.	`--setup <code> [--operations a.b,c.d]`
`sync-faustine-adapter`	Update the adapter's registry after a Server Action or data function is added, renamed or removed.	`[--check] [--operations a.b,c.d]`

Install the Web Agent

To install the agent in your app:

In the portal, go to Web Agents and select your agent.
In the Overview tab, find the Install the assistant card and copy your agent ID. For a Next.js agent, the card shows the whole command.
In your coding agent, run the skill with the ID:
```
/install-faustine <AGENT_ID>
```
Answer the questions the coding agent asks. It asks only what it cannot read from the repository, such as which app of a monorepo to use.
Review the diff, then merge and deploy with your own pipeline.

The skill reads package.json and the folder layout to find out what kind of app it is, and then does the following:

App	What the skill changes
Next.js (App Router)	Installs `@faustine-ai/next` and `@faustine-ai/web-agent`, adds a client component that renders `<FaustineAgent>`, and renders it once from the root layout.
Next.js (Pages Router)	Installs the same packages and renders the component once in `pages/_app.tsx`.
Single-page app	Installs `@faustine-ai/web-agent` and calls `Faustine.init` once in the entry module.
No bundler	Adds the script tag to the document head.

If the app has a server-side session, the skill also signs an identity token on the server and passes it to the widget. It asks you to add FAUSTINE_IDENTITY_SECRET to your environment and does not write the secret into the repository. See Identity verification.

The skill then runs your build, starts the dev server and checks that the launcher appears once on the page.

Option	Effect
`--env <name>`	Loads that environment of the agent in place of Production.
`--debug`	Opens a debug session from the page, for development and staging installs. See Open a debug session.
`--setup <code>`	Also adds the Faustine adapter. See the next section.

The script tag the skill adds is the same one the portal shows:

index.html

<script src="https://webagent.faustine.ai/embed?wid=<AGENT_ID>" async></script>

Add the adapter to a Next.js app

When the analysis finds operations behind Server Actions or server-only functions, the agent needs the Faustine adapter to call them. The adapter is App Router only.

To install the agent and the adapter together:

In the agent's Overview tab, in the Install the assistant card, select Create install command. The portal puts a setup code in the command. The code starts with fns_, works once and expires after 30 minutes.

Copy the command and run it in your coding agent:

/install-faustine <AGENT_ID> --setup <SETUP_CODE>

When the coding agent shows the list of operations Faustine found, say which ones to leave out.
Review faustine/registry.ts in the diff. It has one line for each operation the agent can call. Remove a line to keep that function private.

install-faustine hands the work over to enable-faustine-adapter, which runs npx faustine-next init. To add the adapter to an app that already has the agent, run /enable-faustine-adapter --setup <SETUP_CODE>. For what the adapter generates, see The Faustine adapter for Next.js.

Warning

Do not commit a setup code or FAUSTINE_IDENTITY_SECRET. The skills are written to keep both out of the repository. Check the diff before you merge.

Keep the adapter in sync

After you add, rename or remove a Server Action, run:

/sync-faustine-adapter

The skill shows the operations that are new since the last sync, asks which ones to add, and applies the change with npx faustine-next sync. It keeps out the lines you removed from the registry. See Keep the adapter in sync.

Troubleshooting

Symptom	Cause	Fix
The coding agent asks for an agent ID	The command was run without one.	Copy the ID from the Install the assistant card.
`This setup code expired — mint a new one in the portal.`	The setup code is older than 30 minutes.	Select Create install command again and use the new command.
The coding agent stops on a Pages Router app when asked for the adapter	The adapter needs the App Router.	Install the agent without `--setup`. The agent then calls route handlers and external APIs only.

Next steps

Agent skills: the skills package and each skill in detail.
Install in Next.js: the same install by hand.
Verify your users with a signed token: what the identity token is and how the secret is used.