shadcn Skills

Purpose and Scope

shadcn Skills are best understood as reusable project knowledge and automation bundles that can be installed into a codebase alongside components, utilities, configuration, docs, and agent instructions. The registry documentation explicitly broadens shadcn distribution beyond React components: a public GitHub repository can become a registry, and registry items can include rules, docs, templates, workflows, conventions, CI files, and MCP configuration. That makes Skills a natural fit for teams that want to standardize how humans and AI coding agents work inside a project, not only how UI primitives are copied into it.

Sources: apps/v4/content/docs/registry/github.mdx, apps/v4/content/docs/changelog/2025-07-universal-registry.mdx

This page focuses on installing and authoring Skills using the same registry mechanics used elsewhere in shadcn/ui. A Skill can contain files such as AGENTS.md, editor rules, Claude or Cursor command files, conventions documentation, theme tokens, registry manifests, validation scripts, or MCP client configuration. The important idea is that the CLI installs source-owned files into a target project, while the registry schema describes what those files are and how they should be distributed. Use this page when you are packaging team practices or AI-agent guidance rather than just a single UI component.

Relevant Source Files

• apps/v4/content/docs/registry/github.mdx — Documents public GitHub repositories as registries, the npx shadcn@latest add <username>/<repo>/<item> install address, supported file categories such as agent workflows and MCP configuration, and requirements for a valid GitHub registry.
• apps/v4/content/docs/changelog/2025-02-registry-schema.mdx — Establishes the updated registry schema as a way to distribute flat JSON-defined code, custom styles, tokens, hooks, animations, Tailwind layers, and third-party registry content.
• apps/v4/content/docs/changelog/2025-07-universal-registry.mdx — Introduces universal registry items that can be distributed to any project without requiring a framework, React, Tailwind, or components.json.
• apps/v4/content/docs/changelog/2025-09-registry-index.mdx — Describes installing items from the registry index without preconfiguring components.json, including automatic registry configuration and the npx shadcn add @scope/item form.
• apps/v4/content/docs/changelog/2025-10-registry-directory.mdx — Introduces the Registry Directory as a browsable list of code registries built into the CLI with no configuration required.
• apps/v4/content/docs/changelog/2026-05-registry-include.mdx — Documents include for composing large source registries, shadcn registry validate, shadcn build, and the loadRegistry and loadRegistryItem exports for dynamic registry routes.

Core Primitives

A Skill starts with a registry item. In shadcn terminology, a registry item is a JSON-described unit of files that the CLI can resolve and copy into a project. The updated registry schema supports more than component source: it covers design-system assets, themes, CSS variables, hooks, animations, Tailwind layers, utilities, and other code-oriented assets. For Skills, that same shape can describe project rules, agent instructions, CLI commands, documentation, and configuration files that help a coding assistant understand how the repository is supposed to be edited.

Sources: apps/v4/content/docs/changelog/2025-02-registry-schema.mdx, apps/v4/content/docs/registry/github.mdx

Universal registry items are the key primitive for Skills that should work outside a specific UI framework. The changelog states that universal items can be distributed to any project and do not require a framework, components.json, Tailwind, or React. That matters because many Skills are repository practices rather than runtime UI code. A testing Skill might install vitest.config.ts, setup files, and testing notes. An agent workflow Skill might install AGENTS.md, .cursor/rules/*, .claude/commands/*, and MCP configuration without caring whether the target project is Next.js, Astro, or a backend service.

Sources: apps/v4/content/docs/changelog/2025-07-universal-registry.mdx, apps/v4/content/docs/registry/github.mdx

MCP configuration is another first-class category in the registry guidance. The GitHub registry page lists .mcp.json and .cursor/mcp.json as example files that can be distributed through a registry item. Treat MCP files as connection configuration for AI clients, while local Skill files such as AGENTS.md or editor rules describe project behavior and conventions. Keeping both in the same Skill lets a team install the instructions and the client connection metadata together, but they still serve different jobs: one teaches the agent how to work, the other tells compatible clients what external tools or registry-aware services to connect to.

Installation Flow

For a public GitHub-hosted Skill, the shortest installation path is to make the repository itself the registry. Add a registry.json file at the repository root, describe the Skill item and its files, and install by address with the CLI. The documented address format is owner/repo/item, so a user can run the add command without a registry server or generated JSON publishing step. The GitHub repository remains the source registry, which is useful for Skills because the authoritative rules, docs, and automation live next to their review history.

Sources: apps/v4/content/docs/registry/github.mdx

npx shadcn@latest add <username>/<repo>/<item>

If a Skill is published through the registry index, the install flow becomes even shorter. The registry index changelog shows that users can search, view, and add indexed items without manually configuring components.json; the CLI automatically adds the registry configuration for them. The Registry Directory complements that by giving users a browsable list of registries they can pull code and components from, with no extra configuration required. For teams distributing Skills publicly, this turns discovery into part of the install workflow instead of a separate README-only convention.

Sources: apps/v4/content/docs/changelog/2025-09-registry-index.mdx, apps/v4/content/docs/changelog/2025-10-registry-directory.mdx

npx shadcn add @ai-elements/prompt-input

What a Skill Can Include

The registry documentation is intentionally broad about distributable content. It names components, helpers, design-system packages, feature kits, project conventions, codemods, testing setup, CI workflows, project automation, issue templates, pull request templates, agent workflows, and MCP configuration. A practical shadcn Skill can combine these categories into one installable unit: for example, a “repository-maintainer” Skill might install AGENTS.md, docs explaining branch and review conventions, .github/pull_request_template.md, scripts for release checks, and .cursor/mcp.json for an MCP-aware coding client.

Sources: apps/v4/content/docs/registry/github.mdx

Theming and design guidance can also be part of a Skill when the Skill is meant to shape UI output. The registry schema update explicitly calls out custom styles, design-system components, tokens, themes, CSS variables, hooks, animations, and Tailwind layers. That means an AI-facing design Skill does not need to be limited to prose prompts; it can install the concrete theme files and utilities the agent should use. The strongest Skill packages pair instructions with source files, so generated or edited code follows the same naming, token, and composition rules as hand-written code.

Sources: apps/v4/content/docs/changelog/2025-02-registry-schema.mdx

Registry Authoring and Validation

When a Skill grows beyond a single item, use source-registry composition instead of maintaining one large manifest by hand. The registry include changelog introduces include, which lets a root registry.json compose multiple nested registry files. Included files may omit root metadata such as name and homepage, while the root registry provides that metadata. For a Skills repository, this allows separate manifests for agent workflows, MCP configuration, testing setup, and theming assets while still producing one flattened registry output for consumers.

Sources: apps/v4/content/docs/changelog/2026-05-registry-include.mdx

{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "include": [
    "components/ui/registry.json",
    "hooks/registry.json"
  ]
}

Before publishing or asking users to install a Skill, validate the source registry. The documented command npx shadcn registry validate checks the root registry, included registry files, item schema errors, duplicate item names, include rules, and local item paths. Validation runs against source registry files directly and does not require a build first. That is especially important for Skills because broken file paths can silently remove critical instructions or MCP configuration from the package a user expects to install.

Sources: apps/v4/content/docs/changelog/2026-05-registry-include.mdx

npx shadcn registry validate

Compact Command and File Reference

Next Steps

To create a shadcn Skill, start by deciding whether it is project-agnostic. If it should apply to any repository, model it as a universal registry item and avoid framework assumptions. Next, place the actual instructions, configuration, theme assets, scripts, or MCP files in the repository and describe them in registry.json. For small public packages, the GitHub registry flow is enough. For larger packages, split manifests with include, validate with the registry command, and consider submitting the registry to the public index or directory so users can discover and install the Skill without manual configuration.

Sources: apps/v4/content/docs/changelog/2025-07-universal-registry.mdx, apps/v4/content/docs/registry/github.mdx, apps/v4/content/docs/changelog/2025-09-registry-index.mdx, apps/v4/content/docs/changelog/2025-10-registry-directory.mdx, apps/v4/content/docs/changelog/2026-05-registry-include.mdx