jalco-shadcn-registry - SKILL.md Agent Skill

name: jalco-shadcn-registry description: Build and maintain the jalco ui shadcn-compatible registry. Use when creating or reviewing registry items, editing registry.json, choosing registry item types, configuring namespaced registries, planning authentication, adding docs metadata, or ensuring MCP/open-in-v0 compatibility.

jal-co/ui shadcn Registry Skill

Use this skill when working on jalco ui registry infrastructure, registry items, or registry-related docs.

Required reading before changes

Before implementing registry work, the agent MUST read:

.pi/skills/components-build/SKILL.md — the engineering standard every registry item must meet
AGENTS.md
registry.json
package.json
.pi/skills/vercel-react-best-practices/SKILL.md
.pi/skills/vercel-composition-patterns/SKILL.md
.pi/skills/tailwind-design-system/SKILL.md

When needed, the agent SHOULD also inspect:

components.json
public/r
registry/
components/open-in-v0-button.tsx
app/page.tsx

What this skill covers

creating new registry items
choosing the correct registry item type
updating registry.json
validating files, target, dependencies, and registryDependencies
organizing items under registry/[style]/...
planning namespaced registries
preparing for MCP compatibility
planning Open in v0 compatibility
documenting installation and usage
evaluating item types: registry:component, registry:block, registry:ui, registry:lib, registry:hook, registry:style, registry:theme, registry:base, or registry:item

Core rules from shadcn registry docs

Registry basics

The registry MUST expose a root registry.json payload.
registry.json MUST validate against https://ui.shadcn.com/schema/registry.json.
Registry items MUST conform to https://ui.shadcn.com/schema/registry-item.json.
The shadcn build command generates item payloads under public/r by default.
The registry index SHOULD maintain useful titles and descriptions.

File organization

Source files SHOULD be placed under registry/[style]/[item-name]/....
For grouped items, internal folders like components/, hooks/, and lib/ SHOULD be used.
Imports inside registry source MUST use the @/registry/... path when referencing registry-local files.
File structure MUST be intentional and installable.

Choosing item types

The agent MUST use the smallest correct type:

registry:component for simple components
registry:ui for reusable UI primitives and single-file primitives
registry:block for multi-file installable blocks and richer examples
registry:hook for hooks
registry:lib for utilities and non-component code
registry:page for route/page files
registry:file for miscellaneous targeted files
registry:theme for theme tokens
registry:style for styles
registry:base for full design-system base configuration
registry:item for universal or framework-agnostic items

files and targets

Every file entry MUST include path and type.
target is REQUIRED for registry:page and registry:file.
Explicit targets SHOULD be used for universal items.
Target paths MUST be clear, intentional, and safe.

Dependencies

dependencies MUST be used for npm packages.
devDependencies MUST only be used for development-only packages.
registryDependencies MUST be used for shadcn items, namespaced items, or remote registry item URLs.
Dependencies MUST be complete and accurate.
Dependency sets SHOULD be minimal.

Metadata quality

title and description MUST have useful values.
Meaningful categories and meta SHOULD be provided when they improve discoverability.
docs SHOULD be used to show extra installation/setup guidance when needed.
Descriptions SHOULD help both humans and MCP/AI systems understand the item quickly.

Namespaces

Namespace support SHOULD be planned early.

Namespace rules

Namespace names MUST start with @.
Format MUST be @namespace/resource-name.
Namespace config belongs in components.json under registries.
{name} in registry URLs MUST be supported.
{style} SHOULD be supported when serving style-specific variants.

Suggested jalco ui approach

Start simple, then expand.

Good initial public namespace options:

@jalco for primary public items
@jalco-blocks for blocks if separation becomes useful
@jalco-experimental for unstable items later

Default recommendation:

keep the source registry simple first
design item naming and docs so a namespace strategy can be layered on cleanly later

Authentication

For private registries or future premium/internal variants:

MUST use HTTPS
SHOULD use environment-variable-backed credentials
SHOULD support Bearer token or API key auth for CLI consumers
MAY use query parameter auth when needed for Open in v0 compatibility
MUST NOT commit tokens or real credentials

Open in v0 limitation

Open in v0 does not support:

namespaced registries
cssVars
css
envVars
advanced header-based authentication

If Open in v0 support is required, prefer a public item URL or query-parameter-based auth.

MCP compatibility

The shadcn MCP server works with shadcn-compatible registries without special custom server work.

To stay MCP-friendly:

registry.json MUST be valid and discoverable
Item names MUST be consistent and kebab-case
Descriptions SHOULD be informative
Dependencies MUST be declared accurately
registryDependencies MUST preserve clear relationships
A registry index item MUST be available at the expected root registry endpoint

Open-source registry index

If jalco ui is submitted to the shadcn open-source registry index later:

the registry MUST be publicly accessible
the registry SHOULD be flat at the public endpoint
item payloads MUST be root-addressable
MUST NOT rely on embedded content in the public registry index listing
the final hosted shape MUST be validated against shadcn requirements before submission

jal-co/ui standards for registry work

Every registry item MUST conform to the components-build engineering standard and be:

installable
readable
accessible
polished
documentation-ready
consistent with jalco ui naming and design standards

SHOULD prefer:

strong preview value
practical examples
accurate install guidance
minimal surprises for consumers

MUST NOT include:

vague descriptions
bloated dependency lists
unclear file targets
overly clever item structures
inconsistent item types
undocumented environment variable requirements

Recommended workflow

Create a feature branch: feat/<item-name>.
Read AGENTS.md and relevant local skills.
Inspect similar registry items already in the repo.
Choose the correct item type.
Create files under the correct registry/[style]/... location.
Update registry.json with accurate metadata.
Verify dependencies and registry dependencies.
Create a catalog card preview at components/docs/previews/<registry-name>.tsx with key variants.
Add the sidebar nav entry in lib/docs.ts with badge: "New" and badgeAdded set to today's ISO date.
Run pnpm previews:generate to update the catalog import map.
Generate screenshots via /dev/screenshots — save dark and light PNGs to public/previews/.
Run pnpm registry:build.
Run pnpm build to verify full compilation.
Test the local endpoint in public/r or via the dev server.
Confirm docs/install copy is accurate.
Open a PR using the component template (.github/PULL_REQUEST_TEMPLATE/component.md).
If relevant, verify MCP and Open in v0 implications.

Useful commands

pnpm install
pnpm dev
pnpm registry:build
pnpm dlx shadcn@latest view http://localhost:3000/r/<item-name>.json
pnpm dlx shadcn@latest add http://localhost:3000/r/<item-name>.json

When reviewing registry work

Check for:

valid item type selection
correct files and target usage
complete dependency declarations
good descriptions and categories
installability
consistent registry paths
realistic docs guidance
namespace/auth/MCP/open-in-v0 implications when relevant