Agents

This template is designed to work well with coding agents and LLM-powered tools. It exposes Markdown-first routes for reading context, and it ships an installable Agent Skill for authoring registry items correctly.

Install the Registry Skill

Install the pi-shadcn registry authoring skill from the repository:

npx skills add donotlb/pi-shadcn --skill shadcn-registry

Forks can install the same skill from their own repository:

npx skills add <owner>/<repo> --skill shadcn-registry

After installing the skill, ask for registry work directly:

• "add a button component to the registry"
• "adapt this modal from my app into a reusable registry component"
• "add a reusable hook to the registry"
• "turn this dashboard section into a registry block"

The skill covers all public registry item types, previews, usage docs, dependency metadata, and the scaffold command for creating new items non-interactively.

Point Agents At Markdown

The generated /llms.txt route gives AI tools a compact map of the docs, registry catalog, and item pages.

Use /llms-full.txt when a tool needs expanded context with generated Markdown content inlined.

Every docs page, the registry catalog, and each registry item also has a Markdown route:

• /docs.md
• /docs/agents.md
• /registry.md
• /components/example-card.md

Inspired by Fumadocs, "human" permalinks support Markdown content negotiation too. AI clients can request text/markdown, text/x-markdown, or text/plain in the Accept header on pages like /docs or /components/example-card and receive Markdown without changing URLs.

Static Cloudflare Pages deployments should use the explicit .md routes above, because static hosts cannot negotiate Markdown and HTML from the same URL by request headers.

Recommended Agent Workflow

For registry authoring tasks, agents should:

1. Read AGENTS.md, this docs section, and /llms.txt or /llms-full.txt for project context.
2. Use the shadcn-registry skill when available.
3. Scaffold new items with bun --bun ./scripts/new.ts --type <type> --name <kebab-name> --description "<description>".
4. Add --target for registry:page, registry:file, custom alias installs like @ui/ai/<file>.tsx, and targeted registry:item files; use --file-extension for registry:file and targeted registry:item files.
5. Edit the generated source, _registry.mdx, and _preview.tsx with usage docs, previews, and dependency metadata.
6. Run vp check --fix on touched files, bun --bun ./scripts/doctor.ts, and vp build before handoff when docs, routes, registry JSON, catalog loading, or source loading changed.