# For agents

A skill file, a chooser, and a JSON catalog. The agent installs an orb, wires the app's status onto its state, and can read every param back.

Orbkit is a React component library of WebGL shader orbs — expressive, state-driven orbs you install via the shadcn registry and own as local code.

## What an agent does with it

1. Pick an orb from the chooser below (or the full catalog in https://orbkit.zzzzshawn.cloud/llms.txt).
2. Install it with the shadcn CLI. The runtime file comes with it.
3. Map the app's status onto `state` — idle, thinking, speaking. That is the whole integration.
4. If asked to tune the look, read the orb's params from https://orbkit.zzzzshawn.cloud/api/v1/components/%3Cslug%3E and pass `params`, or retune a state with `statePresets`.

## How to call it

1. Put https://orbkit.zzzzshawn.cloud/skill.md and https://orbkit.zzzzshawn.cloud/skill/recipes.md in the skills folder the agent already reads.
2. Install an orb: `npx shadcn@latest add https://orbkit.zzzzshawn.cloud/r/shdr-11.json`
3. Ask for the UI. One orb, driven by state.

```tsx
import { Shdr11 } from "@/components/ui/shdr-11";

const orbState =
  status === "connecting" ? "thinking"
  : isAgentSpeaking ? "speaking"
  : "idle";

<Shdr11 size={320} state={orbState} />
```

## Chooser

| The ask | Try first | 
| --- | --- |
| A voice-assistant avatar with a clear state read | shdr-11, shdr-26, shdr-13 |
| Calm glass for a product hero or a loading state | shdr-01, shdr-25, shdr-21 |
| Retro, terminal, pixel, CRT, print | shdr-23, shdr-14, shdr-28, shdr-29, shdr-33, shdr-27 |
| Nature: water, weather, cloud | shdr-16, shdr-20, shdr-21, shdr-17 |
| Cosmic: galaxy, crystal, corona | shdr-32, shdr-18, shdr-31, shdr-22 |
| Ornament and pattern | shdr-02, shdr-19, shdr-30 |

## Rules

- One orb per agent, driven by `state`. Map your connection status onto idle / thinking / speaking; do not animate the orb yourself.
- Override only params the orb declares. Fetch /api/v1/components/<slug> for the exact keys, ranges and defaults; do not invent keys.
- Retune a state with `statePresets` / `stateColors` (merged key by key), not by forking the orb file.
- Feed a real signal through `volumes` (input = user speech energy, output = agent speech energy, both 0..1) when you have one; otherwise leave it synthesized.
- Keep mounted orbs under about a dozen per page — each is a WebGL context and browsers cap those near 16. `pauseOffscreen` (default true) handles scrolling, not count.
- Install through the shadcn CLI, never npm. Two files land: components/ui/orbkit-core.tsx (the runtime) and components/ui/<slug>.tsx (the orb). They import nothing but React.
- The runtime is a client component; the orb renders nothing on the server and needs no dynamic import. It respects prefers-reduced-motion by drawing one static frame.
- Use the `wrapper` prop for a bezel (glass, ring, dotted, ticks, reticle, grid, halftone, scanlines). Never wrap the canvas in your own border that changes its footprint.

## Try it

### Voice assistant

Build the call screen for our voice agent. It has connecting, listening, and speaking states from the SDK.

Use an Orbkit orb as the avatar. Map connecting to thinking, listening to idle, speaking to speaking. Feed the mic level into volumes.input. Don't animate it yourself.

### Landing hero

Add a hero object to the landing page — something alive but calm.

Use an Orbkit orb in its idle state with the glass wrapper. Size 420. Don't add a border or a shadow around it.

### Retune

The thinking state on our orb is too busy for the dashboard.

Read the orb's params from the API and pass a statePresets override for thinking only. Keep idle and speaking as shipped.

## Links

- llms.txt: https://orbkit.zzzzshawn.cloud/llms.txt
- Skill: https://orbkit.zzzzshawn.cloud/skill.md
- Recipes: https://orbkit.zzzzshawn.cloud/skill/recipes.md
- JSON catalog: https://orbkit.zzzzshawn.cloud/api/v1/components
- OpenAPI: https://orbkit.zzzzshawn.cloud/openapi.json
- Developer API: https://orbkit.zzzzshawn.cloud/developers
- Playground: https://orbkit.zzzzshawn.cloud/playground
- Source: https://github.com/zzzzshawn/orbkit