🤖 CDS AI Agent Skills

Agent Skills for the Central Design System (CDS 4) design system, made for AI agents (Claude Code and compatible ones). Skills fire automatically based on what you ask — you don't have to name them.

There are three of them, split by task so that a question about migration doesn't drag in knowledge about building interfaces:

Skill	What it covers
cds-builder	Build UI, plug in the library, themes and tokens
cds-migrate	Move a project from CDS 3 to CDS 4
cds-refactor	Review code and convert someone else's markup to CDS

🚀 Installation

Two steps: add the package, then run the installer.

Step 1 — the package as a dev dependency:

npm

npm install -D @central-design-system/skills@next

pnpm

pnpm add -D @central-design-system/skills@next

yarn

yarn add -D @central-design-system/skills@next

bun

bun add -D @central-design-system/skills@next

Step 2 — the installer. It runs the local cds-skills binary, which copies all three skills into .claude/skills/ of the current project:

npm

npx cds-skills install

pnpm

pnpm exec cds-skills install

yarn

yarn cds-skills install

bun

bunx cds-skills install

A one-off install straight from the registry, without adding the package to the project:

npm

npx --package @central-design-system/skills@next cds-skills install

pnpm

pnpm dlx --package @central-design-system/skills@next cds-skills install

yarn

yarn dlx --package @central-design-system/skills@next cds-skills install

bun

bunx --package @central-design-system/skills@next cds-skills install

The remaining commands below are written with npx — substitute the runner of your own package manager from step 2:

npm

npx cds-skills install cds-builder      # only the one you need
npx cds-skills install --dir <path>     # a different skills directory
npx cds-skills list                     # what is available and what is installed

pnpm

pnpm dlx cds-skills install cds-builder      # only the one you need
pnpm dlx cds-skills install --dir <path>     # a different skills directory
pnpm dlx cds-skills list                     # what is available and what is installed

yarn

yarn dlx cds-skills install cds-builder      # only the one you need
yarn dlx cds-skills install --dir <path>     # a different skills directory
yarn dlx cds-skills list                     # what is available and what is installed

bun

bunx cds-skills install cds-builder      # only the one you need
bunx cds-skills install --dir <path>     # a different skills directory
bunx cds-skills list                     # what is available and what is installed

🔄 Updating

Repeat step 1 with the next tag, then run the installer from step 2 again — it overwrites the installed copies.

npx cds-skills list shows the installed version — the same one lives in GENERATION.md of every skill (CDS version, git SHA, date and generation stats).

cds-builder

The main skill. Building an interface, plugging in the library, themes and tokens.

When it fires

• building any UI: a form, a page, a table, a card, a modal, a dashboard, a header;
• plugging CDS into a new or existing project, configuring createCds, styles, Tailwind;
• questions about the contract: "what props does CdsSelect have", "does CdsButton have a variant";
• themes, brand palette, tokens, bundle size;
• building from a screenshot or a mockup.

Example requests: "build a sign-in form on CDS with validation", "install CDS in my project", "lay out an order list page", "add a custom theme", "here is a screenshot, build it on CDS".

What it does. Reads the project context (CDS version, bundler, TypeScript, whether Tailwind is present), picks a component through a decision tree, checks every prop against the contract and returns a working SFC. The key rule of the skill is never to invent props: an invented prop looks plausible and silently does nothing.

Output format: complete working code with imports → 2–4 sentences about the decisions made (for a trivial request — no explanation at all).

Contract linter. The skill ships a mechanical check of the generated markup — every Cds* tag in the given .vue files is checked against the API reference (the component exists, every prop and event is real):

node .claude/skills/cds-builder/scripts/check-contracts.mjs src/components/MyForm.vue

The agent runs it on the files it created; you can also wire it into CI or a pre-commit hook. Exit code 0 — clean, 1 — problems found. cds-refactor uses the same script to verify code before and after a rewrite.

Reference files (loaded on demand):

File	What's inside	When it loads
references/component-decision-tree.md	What every component is for, plus a breakdown of similar pairs	The component isn't named, or the choice is in doubt
references/components/<name>/api.md	The full contract: props / events / slots / exposed	Always, before using a component
references/components/<name>/examples.md	Usage examples	A working pattern is needed
references/components/<name>/guidelines.md	Do / Don't rules	Not present for every component
references/components/<name>/tokens.md	Local SCSS variables	Fine-tuning styles
references/tokens/	Themes and palette	Working with color and themes
references/guides/	Installation, conventions, forms, theming, Tailwind, tree-shaking, responsiveness	Depends on the topic
references/patterns/	Playbooks: form, page shell, list table, modal	A whole complex screen

cds-migrate

Moving a project from CDS 3 to CDS 4.

When it fires

• bumping the CDS version, something broke after the update;
• [CDS UPGRADE] warnings in the console;
• CDS 3 patterns in the code: dist/cds.css, @central-design-system/icons, CdsDropdown, CdsRadioButton, CdsProgress, CdsTabsV2, CdsCheckboxGroup, CdsContainer — even if the word "migration" never came up.

Example requests: "migrate the project to CDS 4", "styles fell apart after the update", "it can't find dist/cds.css", "what changed in CDS 4".

What it does. Surveys the project and shows the scope of work before making any edits, then goes step by step: package and styles entry point → icons → component and prop renames → CSS architecture → composables and exports. It ends with a verification checklist and says honestly what is left uncovered.

Reference file: references/migration-full.md — the full migration guide with every Before / After pair.

cds-refactor

Reviewing existing code and converting someone else's markup to CDS.

When it fires

• review: "check this", "what's wrong here", "am I using CdsSelect correctly";
• conversion: plain HTML/CSS → CDS, hand-rolled Tailwind controls → CDS;
• cleanup: hardcoded colors instead of tokens, form fields assembled by hand, accessibility problems.

Example requests: "review my component", "convert this markup to CDS", "replace my own buttons with CdsButton", "drop the hardcoded colors".

Output modes

• Review only → a breakdown by importance: Critical / Improvements / Optional, with the smallest possible fix for each finding.
• Refactor → rewritten code + a list of changes + suggestions.
• Both → the breakdown first, then the code.

Behavior is preserved either way: handlers, state and conditional rendering are carried over as they are. A partially converted working component beats a fully converted broken one.

Reference files: references/html-to-cds.md, references/tailwind-to-cds.md (mapping tables), references/review-checklist.md (the review checklist).

Refactoring does not strip Tailwind out of the project: CDS 4 is integrated with Tailwind CSS v4, and laying out with utilities is the recommended approach. Only hand-rolled controls get replaced.

This skill does not handle migration from CDS 3 — cds-migrate is there for that.

📂 Package structure

@central-design-system/skills
├── bin/cds-skills.mjs      # installer
├── .claude-plugin/plugin.json
└── skills/
    ├── cds-builder/
    │   ├── SKILL.md
    │   ├── GENERATION.md
    │   ├── scripts/check-contracts.mjs
    │   └── references/
    │       ├── component-decision-tree.md
    │       ├── components/<name>/{api,examples,guidelines,tokens}.md
    │       ├── tokens/{themes,colors}.md
    │       ├── guides/
    │       └── patterns/
    ├── cds-migrate/
    │   ├── SKILL.md
    │   ├── GENERATION.md
    │   └── references/migration-full.md
    └── cds-refactor/
        ├── SKILL.md
        ├── GENERATION.md
        └── references/{html-to-cds,tailwind-to-cds,review-checklist}.md

The heavy component reference lives in cds-builder only and is not duplicated; cds-migrate and cds-refactor link to it, and if it isn't installed — to the llms/ directory from the library's npm package.

🧩 Agents without skill support

For Cursor, Copilot, Windsurf and others there is a catalog following the llmstxt.org convention — it ships both in the library's npm package (node_modules/@central-design-system/components/llms/) and on the documentation site:

File	What's inside
llms.txt	Index: the documentation sets and what every component is for
llms-full.txt	Everything at once: guides, tokens, components, migration
llms-components.txt	Components only: purpose, examples, API contract
llms-tokens.txt	Tokens and themes only
llms-guides.txt	Guides only
llms-migration.txt	CDS 3 → CDS 4 migration only

Add a pointer to the file you need in your product's instructions (AGENTS.md, .cursorrules, .github/copilot-instructions.md). More on the LLMs.txt page.

🛠️ Regeneration (for CDS developers)

The contents of the skills are generated in the monorepo:

cd packages/components
bun run generate:meta    # if components changed
bun run generate:skill

The cds-builder/, cds-migrate/ and cds-refactor/ directories are disposable — do not edit them by hand. Handwritten content lives in packages/components/build/plugins/:

• generate-skill/content/<skill>/ — the body of SKILL.md, playbooks, mapping tables, the breakdown of similar pairs;
• content/guides/ — guides shared with the llms/ reference.