# Set up blocks

> Have your agent connect a project to the shadcn/ui Pro registry, check the setup and prove it by installing a block, with fixes for the usual errors.

## Usage

### Run the skill

In your editor's chat, in the project you want to set up:

```text title="Prompt"
/shadcnpro-setup-blocks
```

### Add your license key

When the agent asks, create a key in [Account → License keys](https://pro.shadcn.co/account/license-keys) and add it to `.env.local` yourself. Don't paste it into the chat.

### Check the test install

The agent installs one block to prove that everything works, and tells you what it changed.

This is the agent's version of [Installation](https://pro.shadcn.co/docs/installation). Use whichever you prefer: the result is the same.

## What the skill does

1. Reads the project with `npx shadcn@latest info --json`: the framework, the Tailwind CSS version, the style and the registries.
2. Runs `npx shadcn@latest init` if the project has no `components.json` yet. It asks first, because `init` edits your stylesheet and installs packages.
3. Checks that the license key is in `.env.local` and that git ignores the file.
4. Adds the `@shadcnpro` registry to `components.json`, next to the settings that are already there.
5. Checks a free block and a block that needs a plan with `npx shadcn@latest view`, which writes nothing.
6. Installs a block, the one you came for or a small free one, after a dry run that shows what will change.
7. Checks that the files exist, that the project still type-checks, and that the block matches your UI library.

It skips every step whose check already passes, so it's safe to run in a project that is half set up.

## Your license key stays private

The key belongs in `.env.local` and nowhere else. The skill is written to keep it there:

- It asks you to add the key, and checks that the line exists without printing the file.
- It never writes the key into `components.json`, source files or its replies.
- It adds `.env.local` to `.gitignore` when git doesn't ignore it yet.
- If it finds a key written directly into `components.json`, it moves it out and tells you to revoke that key if the file was ever committed.

## Free blocks only

No plan yet? Tell the agent. It registers the registry without the key, and you can install the 62 free blocks. See [Free blocks without a license key](https://pro.shadcn.co/docs/installation#free-blocks-without-a-license-key).

## Your files are safe

When a block brings a file your project already has, such as a `components/ui` file you changed, the skill keeps your version and installs the rest. It replaces your files only when you ask for the registry's version.

## Errors it fixes

Run the skill whenever an install fails. It knows the messages of the shadcn CLI and their causes:

| The CLI says | The usual cause |
|---|---|
| "Unknown registry "@shadcnpro"" | The registry is missing from `components.json`, or the command ran outside the project. |
| "Registry "@shadcnpro" requires the following environment variables" | `.env.local` has no `SHADCNPRO_LICENSE_KEY`, or the command ran in another folder. |
| "This is a Pro item. Add your license key" | The registry entry has no `headers`. |
| "This license key is invalid or has been revoked" | The key has a typo or was revoked. |
| "Your license key is valid but there is no active Pro subscription" | The plan ended. Check [Account → Billing](https://pro.shadcn.co/account/billing). |
| A Base UI or React Aria project gets Radix UI code | The registry URL is missing `?style={style}`. |
| The install looks fine but files are missing | The CLI asked whether to overwrite a file and got no answer. |

## What comes next

- [`/shadcnpro-choose-blocks`](https://pro.shadcn.co/docs/agent-skills/choose-blocks) picks blocks for a page.
- [`/shadcnpro-create-page`](https://pro.shadcn.co/docs/agent-skills/create-page) builds a page from them.
- The [MCP server](https://pro.shadcn.co/docs/mcp/setup) lets the agent search blocks by what they do. The skill uses it when it's connected.
