Register Form

Register Form

Contract

By the end of this skill the consumer has:

• react-hook-form installed (it's an optional peer dep).
• A useForm() instance inside their component.
• A call to usePilotForm(form, { name }). The hook returns the form

unchanged; existing form.register(...) calls keep working.

• Three tools registered under the scoped names, no more, no less.
• Understanding that submit_ walks the form's registered field

refs to locate the ` DOM node. It will NOT fall back to document.forms`.

Iron Law: usePilotForm never wraps, only registers

The hook takes a UseFormReturn and returns the same object unchanged (see packages/agentickit/src/hooks/use-pilot-form.ts line 141). Consumers keep calling form.register(...), form.handleSubmit(...), form.watch(...) exactly as they would without the copilot. Do not suggest an alternate "copilot-aware" form API. There isn't one, and introducing one would break the RHF ecosystem integration.

Phases

Phase 1: install the peer

npm install react-hook-form

It's declared as an optional peer in packages/agentickit/package.json; consumers who don't use forms skip it entirely.

Phase 2: wire useForm

Standard RHF. Pick the type for the field values first:

import { useForm } from "react-hook-form";

type InvoiceFields = { email: string; amount: number };

const form = useForm({
  defaultValues: { email: "", amount: 0 },
});

Phase 3: attach usePilotForm

import { usePilotForm } from "@hec-ovi/agentickit";

usePilotForm(form, { name: "invoice" });

The signature (verified against use-pilot-form.ts):

function usePilotForm(
  form: UseFormReturn,
  options?: {
    name?: string;
    confirm?: { submit?: boolean; reset?: boolean };
  },
): UseFormReturn

name defaults to "form", which is fine for single-form pages. Set it explicitly on multi-form pages so the tool names don't collide.

confirm controls the per-form gate on the auto-registered submit_ and reset_ tools. Both default to true; flip a key to false for low-stakes flows where the approval popup is friction more than safety (e.g. a draft-only "create" wizard whose output the user immediately edits).

Phase 4: render the form normally

  
  
  Send

No wrapper component, no special props. The three scoped tools drive this form via normal RHF APIs (setValue, reset, requestSubmit).

Phase 5: understand the registered tools

With name: "invoice", the hook registers:

• set_invoice_field({ field, value }) writes a single field via

form.setValue(field, value, { shouldValidate: true, shouldDirty: true, shouldTouch: true }). Field path strings like "email" or "address.street" are accepted. Triggers RHF validation so the UI reflects errors immediately. (See use-pilot-form.ts lines 71-91.)

• submit_invoice() calls requestSubmit() on the located form

node so the declared onSubmit handler runs exactly as if the user clicked. Returns { success: false, message } if the form is already submitting or not mounted. mutating: true. (Lines 93-120.)

• reset_invoice() calls form.reset() back to defaultValues.

mutating: true. (Lines 122-132.)

Phase 6: security note

submit_invoice locates the ` DOM node by walking from a registered field's ref up to the nearest ancestor. It will NOT fall back to document.forms; doing so would let the assistant submit any form on the page, including a search bar baked into a host shell. (See findFormElement at use-pilot-form.ts` lines 156-172 and the comment on lines 149-155 explaining why.)

If submit_ returns { success: false, message: "Could not locate the element." }, the form hasn't rendered yet or no fields are registered. Register at least one field via form.register(...) before the AI can submit.

Anti-Patterns

• Calling usePilotForm(form) outside a `` provider. Logs a

dev-only warning and is a no-op (lines 60-68). The user sees no error in prod.

• Forgetting the name on multi-form pages. set_form_field collides

with itself across forms; the last registration wins, chaos ensues.

• Letting the AI submit without the user's eyes on the form. submit_

is already mutating: true; don't also manually register a bypass-confirm version.

• Attempting to expose individual fields via usePilotState. The per-field

state is RHF's internal. Use form.watch() if you want read access, and surface that derived value through usePilotState if truly needed.

Output Format

After wiring, report:

• The form name.
• The three registered tool names (set__field, submit_,

reset_).

• A one-line field-shape summary.

Tools Used

• npm install react-hook-form if not already installed.
• Edit the consumer component to add useForm and usePilotForm.
• Read packages/agentickit/src/hooks/use-pilot-form.ts to verify the

option shape and tool registration.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hec-ovi
• Source: hec-ovi/agentickit
• License: MIT

Install and usage instructions live in the source repository linked above.