feat(skills): ship an agent skill and usage rules in the package

.gitignore

@@ -9,3 +9,4 @@ coverage/
 build/
 test-results/
 playwright-report/
+skills/react-ui/references/

AGENTS.md

@@ -20,7 +20,11 @@ arrives as props.
 - `src/theme.css`, `src/styles.css`: tokens and keyframes; the prebuilt sheet
   entry.
 - `stories/`: Storybook stories, kept out of `src/` so they never ship in `dist/`.
-- `scripts/dep-guard.mjs`, `scripts/contrast-test.mjs`: the CI gates.
+- `scripts/dep-guard.mjs`, `scripts/contrast-test.mjs`, `scripts/agent-references.mjs`:
+  the CI gates; the last is the build step that generates
+  `skills/react-ui/references/` and fails on a public module no group lists.
+- `skills/react-ui/`: the agent skill that ships in the package. `SKILL.md` and
+  `AGENTS.md` are hand-written; `references/` is generated and git-ignored.
 - `scripts/test-dom-setup.ts`: happy-dom preload for unit tests (`bunfig.toml`).
 - `e2e/`: checks against the built package.
 

README.md

@@ -320,6 +320,10 @@ Everything imports from `@corbits/react-ui`, except rows marked "optional peer",
 | `ThemeProvider`     | Persists light, dark or system mode and presets                 |
 | `ThemeToggle`       | Light, dark or system switch                                    |
 
+## For coding agents
+
+The package ships an agent skill: a short guide, usage rules and a props reference for every component. Point your agent at `node_modules/@corbits/react-ui/skills/react-ui` (start with `SKILL.md`), or copy that folder into your agent's skills directory.
+
 ## Using with Interchange
 
 The host app owns the connection to the hub; components only take props.

package.json

@@ -24,6 +24,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -72,7 +73,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && bun run build:css",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && bun run build:css && bun run build:references",
     "prepack": "bun run build",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint",
@@ -82,6 +83,7 @@
     "test:e2e": "bun test ./e2e/exports.test.ts ./e2e/contrast.test.ts && playwright test",
     "check": "bun run typecheck && bun run lint && bun run format:check && bun run test",
     "build:css": "tailwindcss -i src/styles.css -o dist/styles.css && cp src/theme.css dist/theme.css",
+    "build:references": "node scripts/agent-references.mjs",
     "dep-guard": "node scripts/dep-guard.mjs",
     "contrast-test": "node scripts/contrast-test.mjs",
     "stories": "storybook dev -p 6006 --host 127.0.0.1 --no-open",
@@ -115,7 +117,7 @@
     "sonner": "^2.0.7",
     "storybook": "10.6.2",
     "tailwindcss": "^4.3.3",
-    "typescript": "^5.9.3",
+    "typescript": "5.9.3",
     "vite": "^7"
   },
   "peerDependencies": {