AI reference

llms.txt, the agent skill installer, the MCP server and the copy-in registry, rendered from the design system README.

Rendered from the README "AI & agents" section at build time.

Gaudi ships machine-readable docs, an agent skill, a local MCP server and a copy-in block registry. All of it is generated from the sources of truth (owner stories/docs/*.docs.js, READMEs, the story catalogue, coverage.json, public-names.json, tokens, the icon registry and package.json exports) so it cannot drift from the components.

This setup is inspired by reui: its agent skills, MCP server, registry and llms.txt. It also builds on the llms.txt proposal, the shadcn registry spec and the Model Context Protocol with its official TypeScript SDK. See credits.

Regenerate after changing components, docs, stories or tokens. pnpm catalogue:sync now also runs pnpm ai:build; the registry is separate:

pnpm ai:build            # ai/, docs/llm/, llms.txt, llms-full.txt, skill cataloguepnpm ai:check            # fails when any generated file is stalepnpm registry:build      # registry.json + public/r/*.json (--check to verify)pnpm registry:validate   # official shadcn schemas; installs shadcn into node_modules/.cache on first usepnpm test:ai             # search/validate unit tests, skill installer, MCP stdio smoke test

llms.txt

llms.txt follows the llms.txt convention: package summary, install/import/CSS/preset setup, then Foundations, components by category (each linking to docs/llm/<id>.md), Blocks & patterns, MCP & skills, and Registry. Links are repository-relative until a docs host is chosen. llms-full.txt concatenates every page (API table, usage, accessibility, notes, examples and the owner README).

Agent skill

npx @gaudi/design-system skills install --agent claude   # defaultnpx @gaudi/design-system skills install --agent all --dir ../my-appnpx @gaudi/design-system skills list

Re-running is idempotent: unchanged files are reported as such and the AGENTS.md section is replaced in place. Before publishing, run the same commands with node /path/to/design-system/bin/gaudi-ds.mjs in place of npx @gaudi/design-system.

MCP server

A local stdio server reads the shipped ai/ metadata (no network). Tools: search, list_components, get_component, get_examples, list_blocks, get_block, get_tokens, get_install_command, validate_usage, get_agent_skill, get_project_setup; prompt: build.

claude mcp add gaudi-ds -- npx -y @gaudi/design-system mcp# before publishing (local checkout):claude mcp add gaudi-ds -- node "/path/to/design-system/bin/gaudi-ds.mjs" mcp

Cursor (.cursor/mcp.json) and Windsurf (~/.codeium/windsurf/mcp_config.json):

{ "mcpServers": { "gaudi-ds": { "command": "npx", "args": ["-y", "@gaudi/design-system", "mcp"] } } }

VS Code (.vscode/mcp.json):

{ "servers": { "gaudi-ds": { "type": "stdio", "command": "npx", "args": ["-y", "@gaudi/design-system", "mcp"] } } }

Codex (~/.codex/config.toml):

[mcp_servers.gaudi-ds]command = "npx"args = ["-y", "@gaudi/design-system", "mcp"]

OpenCode (opencode.json): { "mcp": { "gaudi-ds": { "type": "local", "command": ["npx", "-y", "@gaudi/design-system", "mcp"] } } }. For any client, node /path/to/design-system/bin/gaudi-ds.mjs runs the same server from a repository checkout in place of npx -y @gaudi/design-system. get_block returns block source when public/r exists (a repository checkout); otherwise it returns the install command.

Registry (blocks & patterns)

pnpm registry:build emits a shadcn-compatible registry for the curated examples in coverage.json: page-level blocks (registry:block: app shells, sidebars, screens, dashboards, forms, scheduling, stat cards, chat) and component patterns (registry:example). Each item's file is the owner fixture rewritten by the Storybook publicSource helper, so it imports components from @gaudi/design-system (declared as a dependency) instead of copying them. registry.json is generated; do not edit it by hand, and do not use shadcn build (it would copy the fixtures' relative imports).

The registry is served from https://design.gaudi.site/r. Consumers add the namespace to their components.json:

{ "registries": { "@gaudi": "https://design.gaudi.site/r/{name}.json" } }

npx shadcn@latest add @gaudi/screens-account-settingsnpx shadcn@latest add https://design.gaudi.site/r/screens-account-settings.json

Install the package from GitHub first (pnpm add github:ahmadassaf/design-system), or build the registry with GAUDI_PACKAGE_SPEC=github:ahmadassaf/design-system pnpm registry:build so items declare that spec. Some items reference demo assets (/avatars/…, static/images/…) listed in their docs/meta.assets; supply your own. Copied compositions keep the third-party notice.