agentleFS
ouestlabsouestlabs/audio-ui/.claude/skills/add-registry-item/SKILL.md

add-registry-item

Skill207 starsChanged 34 days agoMITView on GitHub

Add, change, rename or remove an item of the audio/ui shadcn registry in apps/www/src/registry-audio (a block, a demo, a styled element over a primitive, a hook or a lib), and wire it into _registry.ts, categories, the generated manifests and the docs. Use for any work under registry-audio/, even a one-line change to a block, because the generated JSON goes stale otherwise.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All paths below are under apps/www/src/registry-audio/bases/base/ unless they start with apps/.

    line 8
  2. Distinctive:

    Before writing, open the closest existing item of the same kind and copy its shape.

    line 21
  3. Very specific:

    Import audio elements from @/registry-audio/bases/base/audio/elements/...

    line 26
  4. Very specific:

    Add the entry to the matching _registry.ts, through the factories of bases/items.ts: libItem(name, spec) (file lib/<name>.ts unless files …

    line 34
  5. Very specific:

    Run registry:build after the last lint fix, or the generated JSON lags the source.

    line 63

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Add or change a registry item

All paths below are under apps/www/src/registry-audio/bases/base/ unless they start with apps/. The rules for file names, exports, icons and colors are in AGENTS.md ("Registry items"); CONTRIBUTING.md has the long version with a full _registry.ts example.

1. Pick the place and the type

You are addingFile_registry.tsItem type
A styled element over a primitiveaudio/elements/<name>.tsxaudio/_registry.tsregistry:ui
A device: its state, its engine, its face (controlled, no audio)devices/<name>/device.ts, engine.ts, panel.tsxdevices/_registry.tsregistry:lib, registry:lib, registry:ui
A composed screencomponents/<category>/react/block-<component>-<variant>.tsxcomponents/_registry.tsregistry:block
A focused example for the docscomponents/<category>/react/<component>-<feature>-demo.tsx (the Vue, Svelte and web ones are <component>-demo.vue, .svelte and .ts in vue/, svelte/ and web/)components/_registry.tsregistry:example
A hookhooks/use-<name>.tshooks/_registry.tsregistry:hook
Framework-free logiclib/<name>.tslib/_registry.tsregistry:lib

Before writing, open the closest existing item of the same kind and copy its shape. The registry is deliberately small: prefer extending an existing block or demo over adding a near-duplicate, and ask before adding a new block.

2. Write it

  • Elements add appearance only. Behavior (pointer, keyboard, ARIA, value logic) belongs in the primitive: if you need new behavior, switch to the change-primitive skill.
  • Import audio elements from @/registry-audio/bases/base/audio/elements/... and shadcn parts from @/registry/bases/base/ui/....
  • Live signals (playheads, meters, spectra) go through a source or a ref, never a setState per frame.
  • Set a Web Audio parameter with setTargetAtTime, not .value =, so a drag never clicks.
  • Reuse the shared audio glue listed in AGENTS.md ("Shared audio glue"): an engine loads its worklet with loadWorklet (lib/audio-worklet), an instrument block plays chords with usePolyphony. Add the item to registryDependencies.
  • A hook or lib stays free of app imports (@/app/...), since it is copied into other projects.

3. Register it

Add the entry to the matching _registry.ts, through the factories of bases/items.ts: libItem(name, spec) (file lib/<name>.ts unless files says otherwise), hookItem(name, spec) (hooks/<name>.ts), deviceItems(name, parts). Write an item out in full only when it fits none of them (an alias with no file, files of several types):

  • name is the install name (npx shadcn add @audio-ui/<name>), usually the file name without extension
  • files[].path is relative to bases/base/
  • target (optional, per file): where the file lands in a project, for the items that belong in a folder of their own. A device's files (device.ts, engine.ts, panel.tsx; the audio.js its worklet runs comes from @audio-ui/engine/kernels, listed in packages/engine/scripts/kernels.ts and written by bun run kernels:build there, and the processors its description uses from @audio-ui/engine/dsp: never import an @audio/* atom in the registry) sit in devices/<name>/ and install to components/audio-ui/devices/<name>/, and the build rewrites every import of them to match. Declare a device with one deviceItems("<name>", { device, engine, panel }) in devices/_registry.ts: it makes the <name>-device, <name>-engine and <name>-panel items, their paths and targets, the dependencies every part has (the state, device-panel, @audio-ui/react) and the <name> item that installs all three. Everything else installs flat by its type.
  • registryDependencies: "@audio-ui/<name>" for our items, "@shadcn/<name>" for shadcn's
  • dependencies: the npm packages the file imports ("@audio-ui/core", "zod")
  • categories (blocks and demos): the category folder at least. A new category also goes in bases/categories.ts (label + description); a category with no items fails the build.

Renaming or removing an item: also search for its old name in apps/www/src/content/docs, skills/audio-ui/ and apps/video/src/showcases, since docs install commands and the shipped skill name items directly (bun test test/skills.test.ts catches the skill).

4. Docs

  • A demo appears in a docs page through <ComponentPreview styleName="base-nova" name="<demo-name>" />.
  • In docs, an installed component is imported as @/components/audio-ui/<name> (where the registry puts it), and its source titled components/audio-ui/<name>.tsx. bun test test/install-paths.test.ts checks every such import.
  • Every hook and lib gets its own entry page, docs/hooks/<name>.mdx or docs/lib/<name>.mdx: frontmatter title (the hook's name, or the lib's file name) and description, then <Entry name="<name>" /> and a ## Usage section with an example checked against the source. List it once in that folder's meta.json, under the ---Group--- it belongs to. Run bun run registry:build so entries.generated.json knows it; test/registry-entries-docs.test.ts fails on an entry with no page or a page with no entry.
  • A component page or an engine guide that uses the hook or the lib says what it does in a sentence and links to its entry, rather than repeating its usage.
  • A new component page: apps/www/src/content/docs/components/base/(<space>)/<name>.mdx ((elements), (workstation) or (devices)), copying the sections of (elements)/knob.mdx (Overview, Installation as <Install name="<name>" packages="..." />, Anatomy, Usage, Interaction, API reference); list it in that space's meta.json, add the slug to CANONICAL_COMPONENT_DOC_SLUGS in apps/www/src/lib/seo.ts, and add it to skills/audio-ui/components.md (and the Component Selection table in skills/audio-ui/SKILL.md).

5. Build and check (from apps/www/)

bun run lint:fix          # first: it reformats the sources
bun run registry:build    # then: regenerates public/r/ and the manifests from the formatted sources
bun run icons:build       # only if you added an icon name
bun run typecheck
bun test

Run registry:build after the last lint fix, or the generated JSON lags the source. Commit the regenerated files with the change.

Then open the page on localhost:4000 (the docs page of its component), use the item with the pointer and the keyboard, and check both themes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.