# Agents

Give AI coding tools the right context for using and authoring this registry.

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:

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

Forks can install the same skill from their own repository:

```sh
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`](/llms.txt) route gives AI tools a compact map of the docs, registry catalog, and item pages.

Use [`/llms-full.txt`](/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.md)
- [`/docs/agents.md`](/docs/agents.md)
- [`/registry.md`](/registry.md)
- [`/components/example-card.md`](/components/example-card.md)

Inspired by [Fumadocs](https://www.fumadocs.dev/docs/headless/utils/negotiation), "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`](/docs) or [`/components/example-card`](/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.