# Register State

> |

- **Type:** Skill
- **Install:** `agentstack add skill-hec-ovi-agentickit-register-state`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hec-ovi](https://agentstack.voostack.com/s/hec-ovi)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hec-ovi](https://github.com/hec-ovi)
- **Source:** https://github.com/hec-ovi/agentickit/tree/main/.pilot/skills/register-state

## Install

```sh
agentstack add skill-hec-ovi-agentickit-register-state
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Register State

## Contract

By the end of this skill the consumer has:

- A call to `usePilotState` inside a `` subtree.
- A Zod schema that describes the value shape precisely enough for the LLM
  to produce valid updates.
- A decision about read-only vs. writable (setter supplied or omitted).
- Understanding that the hook **does not** return state. It only
  registers. State is owned by the consumer's `useState` / store.

## Iron Law: the schema must match the value

`usePilotState` takes `value: T` AND `schema: z.ZodType`. When `setValue`
is supplied, the schema is also handed to the auto-generated
`update_` action as its input schema (see
`packages/agentickit/src/hooks/use-pilot-state.ts` lines 100-113). If the
schema is looser than the TypeScript type (e.g. `z.any()` on a
`{ id: string }`), the AI will produce updates that pass validation but
break the consumer's app at runtime. **If you cannot write a precise Zod
schema, this state slice is not ready to expose.**

## Phases

### Phase 1: confirm the state shape

The hook is a registration, not a store. The consumer must already own the
state:

```tsx
const [total, setTotal] = useState(42);
```

### Phase 2: write the Zod schema

Match the TypeScript type exactly. For primitives:

```tsx
import { z } from "zod";
const totalSchema = z.number();
```

For complex objects, promote the schema to module scope and use
`z.infer` for the corresponding TS type. This keeps the
two in lockstep (see `examples/todo/app/page.tsx` lines 16-24).

### Phase 3: call `usePilotState`

Read-only (AI can see `total` but cannot change it):

```tsx
import { usePilotState } from "@hec-ovi/agentickit";

usePilotState({
  name: "cart_total",
  description: "Current cart total in USD.",
  value: total,
  schema: z.number(),
});
```

Writable (AI can propose whole-value updates through the registered setter):

```tsx
usePilotState({
  name: "cart_total",
  description: "Current cart total in USD.",
  value: total,
  schema: z.number(),
  setValue: setTotal,
});
```

Passing `setValue` auto-registers an action named `update_cart_total` with
`mutating: true`, so the user will see a confirm prompt before the write
lands (see `use-pilot-state.ts` line 112). Do NOT also register a manual
`set_cart_total` action; it'll duplicate.

### Phase 4: name conventions

- `name` must be a stable identifier (snake_case recommended). It becomes
  the key the LLM sees in the `context` block and the suffix of
  `update_` when a setter is supplied.
- Two components registering the same `name` triggers a dev-mode
  `console.warn` (see `components/pilot-provider.tsx` line 124-130);
  the later registration wins. Don't rely on this; pick unique names.

### Phase 5: verify

Open the sidebar, ask "what's the current cart total?". The assistant
should quote the number from the state. If it doesn't:

- Confirm the hook is inside `` (outside it, a dev warning fires
  and the hook is a no-op; see `use-pilot-state.ts` line 62-66).
- Confirm the value changes are propagating (the hook re-pushes via
  `updateStateValue` on every `value` identity change; see lines 91-94).

## Anti-Patterns

- Using `z.any()` or `z.unknown()` as the schema. The LLM gets no
  structural hint, and when `setValue` is supplied the `update_`
  action is effectively unconstrained.
- Registering derived state. If `doneCount` is `todos.filter(t => t.done).length`,
  expose `todos` and let the model count. Derived state goes stale.
- Passing an inline `z.number()` on every render. It's safe (the hook
  stores the schema in a ref and reads lazily), but it's a code smell.
  Hoist the schema to module scope.
- Exposing secrets: auth tokens, PII, internal IDs. Whatever you register
  is serialized and sent to the model provider on every turn.

## Output Format

After registration, report:

- The state `name` and a one-line shape description.
- Whether it's read-only or writable.
- If writable: confirm the consumer knows an `update_` tool now
  exists and will confirm before calling their setter.

## Tools Used

- Edit the component file to add the `usePilotState` call.
- Read `packages/agentickit/src/hooks/use-pilot-state.ts` to confirm the
  option shape is current.

## 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](https://github.com/hec-ovi)
- **Source:** [hec-ovi/agentickit](https://github.com/hec-ovi/agentickit)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hec-ovi-agentickit-register-state
- Seller: https://agentstack.voostack.com/s/hec-ovi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.