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.
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- skills/audio-ui/AGENTS.mdAGENTS.md
- skills/core/AGENTS.mdAGENTS.md
- skills/design/AGENTS.mdAGENTS.md
- skills/web-audio/AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- change-primitiveSkill
- film-componentSkill
- audio-uiSkill
- coreSkill
- designSkill
- web-audioSkill
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
- Very specific: line 8
All paths below are under apps/www/src/registry-audio/bases/base/ unless they start with apps/.
- Distinctive: line 21
Before writing, open the closest existing item of the same kind and copy its shape.
- Very specific: line 26
Import audio elements from @/registry-audio/bases/base/audio/elements/...
- Very specific: line 34
Add the entry to the matching _registry.ts, through the factories of bases/items.ts: libItem(name, spec) (file lib/<name>.ts unless files …
- Very specific: line 63
Run registry:build after the last lint fix, or the generated JSON lags the source.
≈ “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.
Files
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 adding | File | _registry.ts | Item type |
| A styled element over a primitive | audio/elements/<name>.tsx | audio/_registry.ts | registry:ui |
| A device: its state, its engine, its face (controlled, no audio) | devices/<name>/device.ts, engine.ts, panel.tsx | devices/_registry.ts | registry:lib, registry:lib, registry:ui |
| A composed screen | components/<category>/react/block-<component>-<variant>.tsx | components/_registry.ts | registry:block |
| A focused example for the docs | components/<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.ts | registry:example |
| A hook | hooks/use-<name>.ts | hooks/_registry.ts | registry:hook |
| Framework-free logic | lib/<name>.ts | lib/_registry.ts | registry: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-primitiveskill. - 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
setStateper 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 withloadWorklet(lib/audio-worklet), an instrument block plays chords withusePolyphony. Add the item toregistryDependencies. - 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):
nameis the install name (npx shadcn add @audio-ui/<name>), usually the file name without extensionfiles[].pathis relative tobases/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 inpackages/engine/scripts/kernels.tsand written bybun run kernels:buildthere, and the processors its description uses from@audio-ui/engine/dsp: never import an@audio/*atom in the registry) sit indevices/<name>/and install tocomponents/audio-ui/devices/<name>/, and the build rewrites every import of them to match. Declare a device with onedeviceItems("<name>", { device, engine, panel })indevices/_registry.ts: it makes the<name>-device,<name>-engineand<name>-panelitems, 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'sdependencies: the npm packages the file imports ("@audio-ui/core","zod")categories(blocks and demos): the category folder at least. A new category also goes inbases/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 titledcomponents/audio-ui/<name>.tsx.bun test test/install-paths.test.tschecks every such import. - Every hook and lib gets its own entry page,
docs/hooks/<name>.mdxordocs/lib/<name>.mdx: frontmattertitle(the hook's name, or the lib's file name) anddescription, then<Entry name="<name>" />and a## Usagesection with an example checked against the source. List it once in that folder'smeta.json, under the---Group---it belongs to. Runbun run registry:buildsoentries.generated.jsonknows it;test/registry-entries-docs.test.tsfails 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'smeta.json, add the slug toCANONICAL_COMPONENT_DOC_SLUGSinapps/www/src/lib/seo.ts, and add it toskills/audio-ui/components.md(and the Component Selection table inskills/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 testRun 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.
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
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.

