@hugocxl/ai 0.0.0-stage → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hugo Corta
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,108 @@
1
- # Temporary Holding Version
1
+ # @hugocxl/ai
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ ### One stack. Every agent builds it the same way.
4
+
5
+ Four libraries, designed to work as one, and the instructions that teach AI agents to use them
6
+ together. Whichever agent you work with (Claude Code, Codex, Cursor, Copilot, Gemini…) and
7
+ whichever project you start, the result follows the same rules.
8
+
9
+ | Library | What it does | Agent skill |
10
+ | --- | --- | --- |
11
+ | [@hugocxl/design-system](https://hugocxl.github.io/stack/design-system/) | Gives everything its type, color and space | `design-system` |
12
+ | [@hugocxl/icons](https://hugocxl.github.io/stack/icons/) | Labels what people can do | `icons` |
13
+ | [@hugocxl/vectors](https://hugocxl.github.io/stack/vectors/) | Illustrates what you mean | `vectors` |
14
+ | [@hugocxl/sounds](https://hugocxl.github.io/stack/sounds/) | Makes it feel like something | `sounds` |
15
+
16
+ ## How it works
17
+
18
+ - **Each library ships its own skill** inside its npm package (`skills/<name>/SKILL.md`), so
19
+ the instructions always match the version a project has installed. Icons and vectors include
20
+ a catalog search, so agents look names up instead of guessing.
21
+ - **This package adds what no single library can say:** the
22
+ [`stack` skill](skills/stack/SKILL.md) (which library covers which need, icon or vector, how
23
+ colors and sounds pair with the design system, how to start a project) and the rules every
24
+ project shares.
25
+ - **`npx @hugocxl/ai`** puts all of it into a project, keeps it current and checks the code.
26
+
27
+ ## Set up a project
28
+
29
+ ```sh
30
+ npm install @hugocxl/design-system @hugocxl/icons @hugocxl/vectors @hugocxl/sounds
31
+ npx @hugocxl/ai init
32
+ ```
33
+
34
+ `init` writes:
35
+
36
+ - a managed section in **`AGENTS.md`**, read by Codex, Cursor, Copilot, Gemini and most other
37
+ agents (anything you write outside the markers is kept);
38
+ - a **`CLAUDE.md`** that imports `AGENTS.md`, for Claude Code;
39
+ - the skills of the installed libraries, plus the `stack` skill, in **`.agents/skills/`** and
40
+ **`.claude/skills/`**.
41
+
42
+ Commit them. After installing or upgrading a library, run `npx @hugocxl/ai sync`.
43
+
44
+ ## Check a project
45
+
46
+ ```sh
47
+ npx @hugocxl/ai check
48
+ ```
49
+
50
+ It reads the catalogs of the installed libraries and reports:
51
+
52
+ | Rule | Level | Catches |
53
+ | --- | --- | --- |
54
+ | `agent-files` | error | `AGENTS.md`, `CLAUDE.md` or the skills missing or out of date with the installed libraries |
55
+ | `foreign-icons` | error | Lucide, Heroicons, Font Awesome, Material, Phosphor, react-icons and other icon libraries |
56
+ | `unknown-icon` | error | Icon names, styles, exports and import paths that do not exist |
57
+ | `unknown-vector` | error | Vector names, exports and import paths that do not exist |
58
+ | `unknown-sound` | error | Sounds and haptics that do not exist |
59
+ | `missing-library` | error | An `@hugocxl` library that is imported but not installed |
60
+ | `tailwind-palette` | warning | `bg-blue-500` and other Tailwind default colors next to the design system |
61
+ | `raw-color` | warning | Hex and `rgb()` colors in stylesheets next to the design system |
62
+
63
+ It exits with 1 on errors, so it works in CI and in an agent's own loop. `--strict` treats
64
+ warnings as errors and `--json` prints machine-readable findings. Configure it in
65
+ `package.json`:
66
+
67
+ ```json
68
+ {
69
+ "stack": {
70
+ "rules": { "raw-color": "off", "tailwind-palette": "error" },
71
+ "ignore": ["legacy/**"]
72
+ }
73
+ }
74
+ ```
75
+
76
+ A `stack-ignore` comment skips findings on its line, and `stack-ignore-next-line` on the next.
77
+
78
+ ## Claude Code plugins
79
+
80
+ To have the skills in every Claude Code session without setting up each project, add the
81
+ [stack](https://github.com/hugocxl/stack) monorepo as a plugin marketplace:
82
+
83
+ ```sh
84
+ claude plugin marketplace add hugocxl/stack
85
+ claude plugin install stack@hugocxl
86
+ ```
87
+
88
+ `stack` installs the `design-system`, `icons`, `vectors` and `sounds` plugins with it. Each
89
+ library plugin comes straight from its latest npm release.
90
+
91
+ ## Develop
92
+
93
+ `@hugocxl/ai` lives in [`ai/`](https://github.com/hugocxl/stack/tree/main/ai) of the
94
+ [stack](https://github.com/hugocxl/stack) monorepo, next to the four libraries.
95
+
96
+ ```sh
97
+ pnpm install # at the monorepo root
98
+ cd ai
99
+ pnpm test # the CLI, the rules, the skill and the marketplace
100
+ pnpm run pack:check # the files a publish would include
101
+ ```
102
+
103
+ Every push to `main` that changes `ai/` and passes CI is released as `0.1.<run number>` to npm,
104
+ with provenance, and as a GitHub release tagged `ai-v<version>`.
105
+
106
+ ## License
107
+
108
+ [MIT](LICENSE). Made by [Hugo](https://github.com/hugocxl).
package/bin/ai.mjs ADDED
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env node
2
+ import { main } from '../src/cli.mjs';
3
+
4
+ process.exitCode = await main(process.argv.slice(2));
package/package.json CHANGED
@@ -1,6 +1,55 @@
1
1
  {
2
2
  "name": "@hugocxl/ai",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.3",
4
+ "description": "Set up any project so every AI agent uses the @hugocxl stack (design system, icons, vectors and sounds) the same way.",
5
+ "keywords": [
6
+ "agents",
7
+ "agent skills",
8
+ "AGENTS.md",
9
+ "claude code",
10
+ "design system",
11
+ "icons",
12
+ "lint"
13
+ ],
14
+ "type": "module",
15
+ "bin": {
16
+ "ai": "bin/ai.mjs"
17
+ },
18
+ "exports": {
19
+ ".": "./src/check.mjs",
20
+ "./package.json": "./package.json"
21
+ },
22
+ "files": [
23
+ "bin",
24
+ "src",
25
+ "skills",
26
+ "templates",
27
+ "LICENSE",
28
+ "README.md"
29
+ ],
30
+ "engines": {
31
+ "node": ">=20"
32
+ },
33
+ "license": "MIT",
34
+ "author": "Hugo Corta (https://hugocxl.me)",
35
+ "homepage": "https://hugocxl.github.io/stack/",
36
+ "repository": {
37
+ "type": "git",
38
+ "url": "https://github.com/hugocxl/stack.git",
39
+ "directory": "ai"
40
+ },
41
+ "bugs": "https://github.com/hugocxl/stack/issues",
42
+ "publishConfig": {
43
+ "access": "public"
44
+ },
45
+ "scripts": {
46
+ "test": "node --test tests/*.test.mjs",
47
+ "pack:check": "npm pack --dry-run"
48
+ },
49
+ "devDependencies": {
50
+ "@hugocxl/design-system": "^0.2.10",
51
+ "@hugocxl/icons": "^0.2.29",
52
+ "@hugocxl/sounds": "^0.1.3",
53
+ "@hugocxl/vectors": "^0.1.11"
54
+ }
55
+ }
@@ -0,0 +1,102 @@
1
+ ---
2
+ name: stack
3
+ description: The @hugocxl stack — @hugocxl/design-system, @hugocxl/icons, @hugocxl/vectors and @hugocxl/sounds — used together. Read it first for any interface work in a project that uses the stack, when starting a new @hugocxl project, or when deciding between an icon and an illustration, choosing which library covers a need, or checking that a change follows the stack.
4
+ ---
5
+
6
+ # The @hugocxl stack
7
+
8
+ Four libraries, designed to work as one. Every @hugocxl project builds its interface from them
9
+ and from nothing else, so any agent working on any project produces the same result.
10
+
11
+ | Need | Library | Skill |
12
+ | --- | --- | --- |
13
+ | Type, color, spacing, layout, pages, components | `@hugocxl/design-system` | `design-system` |
14
+ | A symbol that labels an action or a kind of thing | `@hugocxl/icons` | `icons` |
15
+ | An illustration that explains an idea or a state | `@hugocxl/vectors` | `vectors` |
16
+ | Sound or haptic feedback for a direct action | `@hugocxl/sounds` | `sounds` |
17
+
18
+ Read this skill first, then the skill of each library the task touches. Each library's skill
19
+ ships inside its npm package, so it always matches the installed version.
20
+
21
+ ## Rules
22
+
23
+ 1. **Nothing from outside the stack.** No other icon set, illustration, stock image, emoji used
24
+ as an icon, UI kit, theme, color palette, font or interface sound library. If the stack has
25
+ no answer, say so and ask; do not improvise one.
26
+ 2. **The design system decides how things look.** Use its tokens for every color, size, space,
27
+ radius and font, and its components and recipes for pages. See the `design-system` skill.
28
+ 3. **Never guess a name.** Find icon and vector names with the search scripts in their skills,
29
+ and check every name before you finish.
30
+ 4. **Meaning first.** An icon labels an action, a vector explains an idea, a sound confirms what
31
+ the hand did. None of them is decoration.
32
+ 5. **Check before you finish.** Run `npx @hugocxl/ai check` and fix every error.
33
+
34
+ ## Icon or vector?
35
+
36
+ - **Icon** (`@hugocxl/icons`): 16–24 px, inline with words or alone in an icon button; it names
37
+ an action (`search`, `trash`) or a kind (`folder`, `terminal`). Stroke style with the design
38
+ system.
39
+ - **Vector** (`@hugocxl/vectors`): 160 px wide or more, in a figure; it shows a whole idea or
40
+ state (`empty-inbox`, `payment-failed`). Pick it by what the section says.
41
+ - Between 24 and 160 px, choose by role, not size: a label is an icon, an explanation is a
42
+ vector. Never scale an icon up into an illustration or a vector down into an icon.
43
+
44
+ ## How the libraries fit together
45
+
46
+ - **Color.** Icons and vectors draw in `currentColor`, so they follow the design system's `ink`
47
+ and `muted` in both themes. Only icons may take a color: a kind hue
48
+ (`defaultColor('folder')` from `@hugocxl/icons/colors` resolves to the design system's
49
+ `--ds-yellow`) or a status role. Never the accent.
50
+ - **Markup.** In design-system pages, icons carry `class="ds-icon"` and vectors
51
+ `class="ds-vector"`, inside the components DESIGN.md defines.
52
+ - **Sound.** Pair each control with its sound from the `sounds` skill:
53
+
54
+ | Design-system element | Sound |
55
+ | --- | --- |
56
+ | `button` (the one filled button) | `down-primary` on press, `up` on release |
57
+ | Other buttons and icon buttons | `down`, then `up` |
58
+ | Theme switch and other toggles | `latch-down` on, `latch-up` off |
59
+ | Pager, tabs, segmented controls | `tick` |
60
+ | Menu, popover or dialog opening | `open` |
61
+ | `form` result | `success`, `warning` or `error` when the result is known |
62
+
63
+ Links that navigate make no sound. Sounds are optional: give people a setting to turn them off.
64
+
65
+ ## Start a new project
66
+
67
+ ```sh
68
+ npm install @hugocxl/design-system @hugocxl/icons @hugocxl/vectors @hugocxl/sounds
69
+ npx @hugocxl/ai init
70
+ ```
71
+
72
+ `init` writes the stack's section into `AGENTS.md`, points `CLAUDE.md` at it, and copies the
73
+ skills of the installed libraries into `.agents/skills/` and `.claude/skills/`. Run
74
+ `npx @hugocxl/ai sync` after upgrading any library, and commit the result.
75
+
76
+ Then choose the integration the project needs:
77
+
78
+ - **Static site:** serve the design system's `system/` folder and copy component markup from
79
+ DESIGN.md; inline icon and vector SVGs from their JavaScript exports.
80
+ - **React (Next.js, Vite, Astro):** Tailwind v4 with `@import "@hugocxl/design-system/tailwind";`,
81
+ icons from `@hugocxl/icons/react/stroke`, vectors from `@hugocxl/vectors/react/<name>`.
82
+ - **React Native / Expo:** tokens from `@hugocxl/design-system/tokens`, icons and vectors from
83
+ their `/react-native` paths with `react-native-svg`. Sounds are web only.
84
+ - **Swift:** the `Icons` and `Vectors` Swift packages and the token values from
85
+ `@hugocxl/design-system/tokens.json`.
86
+
87
+ ## Work on a task
88
+
89
+ 1. Read the skill of each library the task touches.
90
+ 2. Plan the page or screen: the recipe, the components, the copy you were given, and where each
91
+ icon, vector and sound goes.
92
+ 3. Search for every icon and vector name and read its description.
93
+ 4. Build it with tokens and the libraries' own exports.
94
+ 5. Run `npx @hugocxl/ai check`, fix every error, and look at the result in light and dark at
95
+ phone and desktop widths.
96
+
97
+ ## What `npx @hugocxl/ai check` catches
98
+
99
+ Errors: icon or vector names that do not exist, sound names that do not exist, imports from
100
+ other icon libraries, and agent files that are out of date with the installed libraries.
101
+ Warnings: Tailwind's default palette and raw color values in a project that uses the design
102
+ system. Run `npx @hugocxl/ai check --help` for options.
package/src/check.mjs ADDED
@@ -0,0 +1,265 @@
1
+ // `npx @hugocxl/ai check`: find the mistakes agents make with the stack, using the catalogs of the
2
+ // libraries installed in the project.
3
+ import { execFileSync } from 'node:child_process';
4
+ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
5
+ import { extname, join, sep } from 'node:path';
6
+ import { pathToFileURL } from 'node:url';
7
+ import { libraries, readManifest, settings } from './project.mjs';
8
+ import { plan } from './sync.mjs';
9
+
10
+ export const RULES = {
11
+ 'agent-files': { level: 'error', summary: 'AGENTS.md, CLAUDE.md and the skills match the installed libraries' },
12
+ 'foreign-icons': { level: 'error', summary: 'no icon library other than @hugocxl/icons' },
13
+ 'unknown-icon': { level: 'error', summary: 'every @hugocxl/icons import, export and name exists' },
14
+ 'unknown-vector': { level: 'error', summary: 'every @hugocxl/vectors import, export and name exists' },
15
+ 'unknown-sound': { level: 'error', summary: 'every sound and haptic passed to @hugocxl/sounds exists' },
16
+ 'missing-library': { level: 'error', summary: 'every imported @hugocxl library is installed' },
17
+ 'tailwind-palette': { level: 'warning', summary: "no Tailwind default palette next to the design system's tokens" },
18
+ 'raw-color': { level: 'warning', summary: 'no raw color values in stylesheets next to the design system' },
19
+ };
20
+
21
+ export const FOREIGN_ICON_PACKAGES = [
22
+ /^lucide(-[a-z]+)*$/, /^@lucide\//, /^react-icons(\/|$)/, /^@heroicons\//, /^heroicons$/, /^@phosphor-icons\//, /^phosphor-react$/,
23
+ /^@tabler\/icons/, /^@fortawesome\//, /^@mui\/icons-material/, /^@radix-ui\/react-icons$/, /^@iconify(-json)?\//, /^@iconify\/react$/,
24
+ /^react-feather$/, /^feather-icons$/, /^@ant-design\/icons/, /^ionicons$/, /^@expo\/vector-icons/, /^react-native-vector-icons/,
25
+ /^bootstrap-icons$/, /^react-bootstrap-icons$/, /^remixicon$/, /^@remixicon\//, /^@primer\/octicons/, /^@carbon\/icons/, /^@mdi\//,
26
+ /^unplugin-icons/, /^@hugeicons\//, /^iconoir(-react)?$/, /^@iconscout\//, /^react-ionicons$/, /^@svgr\/.*icons/,
27
+ ];
28
+
29
+ const CODE = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts', '.vue', '.svelte', '.astro', '.html', '.htm', '.md', '.mdx']);
30
+ const STYLES = new Set(['.css', '.scss', '.sass', '.less', '.pcss']);
31
+ const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'out', '.next', '.nuxt', '.svelte-kit', '.astro', '.output', '.vercel',
32
+ '.turbo', '.cache', 'coverage', 'vendor', '.agents', '.claude', 'Pods', 'DerivedData', '.expo']);
33
+ const SKIP_FILES = new Set(['AGENTS.md', 'CLAUDE.md', 'CHANGELOG.md']);
34
+
35
+ /** Turn a glob such as `legacy/**` or `*.test.tsx` into a RegExp over relative paths. */
36
+ export function globToRegExp(glob) {
37
+ let pattern = '';
38
+ for (let i = 0; i < glob.length; i++) {
39
+ const c = glob[i];
40
+ if (c === '*' && glob[i + 1] === '*') { pattern += '.*'; i++; if (glob[i + 1] === '/') i++; }
41
+ else if (c === '*') pattern += '[^/]*';
42
+ else if (c === '?') pattern += '[^/]';
43
+ else pattern += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
44
+ }
45
+ return new RegExp(`^${pattern}(/.*)?$`);
46
+ }
47
+
48
+ /** Source files to check: git's tracked and untracked files when possible, otherwise a walk. */
49
+ export function sourceFiles(root, ignore = []) {
50
+ const ignored = ignore.map(globToRegExp);
51
+ let files;
52
+ try {
53
+ files = execFileSync('git', ['ls-files', '-co', '--exclude-standard'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1 << 28 })
54
+ .split('\n').filter(Boolean);
55
+ } catch {
56
+ files = [];
57
+ const walk = dir => {
58
+ for (const entry of readdirSync(join(root, dir), { withFileTypes: true })) {
59
+ const path = dir ? `${dir}/${entry.name}` : entry.name;
60
+ if (entry.isDirectory()) { if (!SKIP_DIRS.has(entry.name)) walk(path); }
61
+ else files.push(path);
62
+ }
63
+ };
64
+ walk('');
65
+ }
66
+ return files.filter(file => {
67
+ const parts = file.split('/');
68
+ if (parts.some(part => SKIP_DIRS.has(part)) || SKIP_FILES.has(parts.at(-1))) return false;
69
+ if (ignored.some(re => re.test(file))) return false;
70
+ const ext = extname(file).toLowerCase();
71
+ return (CODE.has(ext) || STYLES.has(ext)) && existsSync(join(root, file)) && statSync(join(root, file)).size < 2_000_000;
72
+ });
73
+ }
74
+
75
+ const exportName = (name, suffix) => name.split('-').map(part => part[0].toUpperCase() + part.slice(1)).join('') + suffix;
76
+
77
+ function lineAt(text, index) {
78
+ let line = 1;
79
+ let last = -1;
80
+ for (let i = text.indexOf('\n'); i !== -1 && i < index; i = text.indexOf('\n', i + 1)) { line++; last = i; }
81
+ return { line, column: index - last };
82
+ }
83
+
84
+ /** `import`, `export … from`, `require()` and `import()` specifiers, with any named bindings. */
85
+ export function importsOf(text) {
86
+ const found = [];
87
+ const named = /\b(?:import|export)\s+(?:type\s+)?(?:([\w$]+)\s*,?\s*)?(?:\{([^}]*)\}|\*\s+as\s+[\w$]+)?\s*from\s*['"]([^'"]+)['"]/g;
88
+ for (const m of text.matchAll(named)) {
89
+ const names = (m[2] ?? '').split(',').map(part => part.trim().replace(/^type\s+/, '').split(/\s+as\s+/)[0].trim()).filter(Boolean);
90
+ found.push({ specifier: m[3], names, index: m.index });
91
+ }
92
+ for (const m of text.matchAll(/\b(?:require|import)\s*\(\s*['"]([^'"]+)['"]\s*\)/g)) found.push({ specifier: m[1], names: [], index: m.index });
93
+ for (const m of text.matchAll(/^\s*import\s+['"]([^'"]+)['"]/gm)) found.push({ specifier: m[1], names: [], index: m.index });
94
+ for (const m of text.matchAll(/@import\s+(?:url\()?['"]([^'"]+)['"]/g)) found.push({ specifier: m[1], names: [], index: m.index });
95
+ return found;
96
+ }
97
+
98
+ async function loadKnowledge(root, libs) {
99
+ const by = Object.fromEntries(libs.map(library => [library.id, library]));
100
+ const knowledge = { installed: new Set(libs.filter(l => l.installed).map(l => l.package)) };
101
+ if (by.icons.installed) {
102
+ const catalog = JSON.parse(readFileSync(join(by.icons.dir, 'dist/catalog.json'), 'utf8'));
103
+ knowledge.icons = new Map(catalog.map(icon => [icon.name, icon]));
104
+ knowledge.iconExports = new Map(catalog.map(icon => [exportName(icon.name, 'Icon'), icon]));
105
+ }
106
+ if (by.vectors.installed) {
107
+ const catalog = JSON.parse(readFileSync(join(by.vectors.dir, 'dist/catalog.json'), 'utf8'));
108
+ knowledge.vectors = new Map(catalog.map(vector => [vector.name, vector]));
109
+ knowledge.vectorExports = new Set(catalog.map(vector => vector.export));
110
+ }
111
+ if (by.sounds.installed) {
112
+ const sounds = await import(pathToFileURL(join(by.sounds.dir, 'dist/index.js')).href);
113
+ knowledge.sounds = new Set(sounds.soundNames);
114
+ knowledge.haptics = new Set(Object.keys(sounds.feedback));
115
+ }
116
+ knowledge.designSystem = by['design-system'].installed;
117
+ return knowledge;
118
+ }
119
+
120
+ const ICON_PATH = /^@hugocxl\/icons(?:\/(js|react|react-native)(?:\/(duotone|solid|stroke))?(?:\/([a-z0-9-]+))?)?$/;
121
+ const VECTOR_PATH = /^@hugocxl\/vectors(?:\/(js|react|react-native)(?:\/([a-z0-9-]+))?)?$/;
122
+
123
+ function checkIconImport({ specifier, names }, k, report) {
124
+ if (['@hugocxl/icons/catalog.json', '@hugocxl/icons/colors', '@hugocxl/icons/package.json'].includes(specifier)) return;
125
+ const m = specifier.match(ICON_PATH);
126
+ if (!m) return report('unknown-icon', `"${specifier}" is not an @hugocxl/icons export. Use /js, /react or /react-native, an optional /stroke, /solid or /duotone, and an optional icon name.`);
127
+ let [, , style, name] = m;
128
+ if (name && ['duotone', 'solid', 'stroke'].includes(name) && !style) { style = name; name = undefined; }
129
+ if (name) {
130
+ const icon = k.icons.get(name);
131
+ if (!icon) return report('unknown-icon', `There is no icon named "${name}". Find one with the icons skill's search script.`);
132
+ if (style && !icon.styles.includes(style)) return report('unknown-icon', `"${name}" has no ${style} style (it has ${icon.styles.join(', ')}).`);
133
+ for (const binding of names) {
134
+ if (binding !== exportName(name, 'Icon')) report('unknown-icon', `"${specifier}" exports ${exportName(name, 'Icon')}, not ${binding}.`);
135
+ }
136
+ return;
137
+ }
138
+ for (const binding of names) {
139
+ const icon = k.iconExports.get(binding);
140
+ if (!icon) report('unknown-icon', `@hugocxl/icons has no export named ${binding}. Find the icon with the icons skill's search script.`);
141
+ else if (style && !icon.styles.includes(style)) report('unknown-icon', `${binding} has no ${style} style (it has ${icon.styles.join(', ')}).`);
142
+ }
143
+ }
144
+
145
+ function checkVectorImport({ specifier, names }, k, report) {
146
+ if (['@hugocxl/vectors/catalog.json', '@hugocxl/vectors/package.json'].includes(specifier)) return;
147
+ const m = specifier.match(VECTOR_PATH);
148
+ if (!m) return report('unknown-vector', `"${specifier}" is not an @hugocxl/vectors export. Use /js, /react or /react-native and an optional vector name.`);
149
+ const [, , name] = m;
150
+ if (name) {
151
+ const vector = k.vectors.get(name);
152
+ if (!vector) return report('unknown-vector', `There is no vector named "${name}". Find one with the vectors skill's search script.`);
153
+ for (const binding of names) if (binding !== vector.export) report('unknown-vector', `"${specifier}" exports ${vector.export}, not ${binding}.`);
154
+ return;
155
+ }
156
+ for (const binding of names) {
157
+ if (!k.vectorExports.has(binding)) report('unknown-vector', `@hugocxl/vectors has no export named ${binding}. Find the vector with the vectors skill's search script.`);
158
+ }
159
+ }
160
+
161
+ const PALETTE = /(?<![\w-])(?:[a-z0-9-]+:)*(?:bg|text|border(?:-[trblxy])?|ring|ring-offset|fill|stroke|from|via|to|outline|divide|placeholder|decoration|accent|caret|shadow)-(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(?:50|[1-9]00|950)(?:\/\d+)?(?![\w-])|(?<![\w-])(?:[a-z0-9-]+:)*(?:bg|text|border)-(?:white|black)(?![\w-])/g;
162
+ const RAW_COLOR = /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\(/g;
163
+
164
+ /** Check one file's text. Returns findings without the file path. */
165
+ export function checkText(file, text, k) {
166
+ const findings = [];
167
+ const lines = text.split('\n');
168
+ const report = (rule, message, index) => {
169
+ const { line, column } = lineAt(text, index);
170
+ if (/stack-ignore/.test(lines[line - 1] ?? '') || /stack-ignore-next-line/.test(lines[line - 2] ?? '')) return;
171
+ findings.push({ rule, message, line, column });
172
+ };
173
+ const ext = extname(file).toLowerCase();
174
+ const imports = importsOf(text);
175
+
176
+ for (const entry of imports) {
177
+ const at = (rule, message) => report(rule, message, entry.index);
178
+ if (FOREIGN_ICON_PACKAGES.some(re => re.test(entry.specifier))) {
179
+ at('foreign-icons', `"${entry.specifier}" is another icon library. Use @hugocxl/icons; the icons skill shows how.`);
180
+ continue;
181
+ }
182
+ const pkg = entry.specifier.match(/^@hugocxl\/[a-z-]+/)?.[0];
183
+ if (!pkg || pkg === '@hugocxl/ai') continue;
184
+ if (!k.installed.has(pkg)) { at('missing-library', `${pkg} is imported but not installed. Run npm install ${pkg}.`); continue; }
185
+ if (pkg === '@hugocxl/icons') checkIconImport(entry, k, at);
186
+ if (pkg === '@hugocxl/vectors') checkVectorImport(entry, k, at);
187
+ }
188
+
189
+ if (k.icons) {
190
+ for (const m of text.matchAll(/data-icon=["']([a-z0-9-]+)["']/g)) {
191
+ if (!k.icons.has(m[1])) report('unknown-icon', `There is no icon named "${m[1]}". Find one with the icons skill's search script.`, m.index);
192
+ }
193
+ }
194
+ if (k.vectors) {
195
+ for (const m of text.matchAll(/data-vector=["']([a-z0-9-]+)["']/g)) {
196
+ if (!k.vectors.has(m[1])) report('unknown-vector', `There is no vector named "${m[1]}". Find one with the vectors skill's search script.`, m.index);
197
+ }
198
+ }
199
+ if (k.sounds && imports.some(entry => entry.specifier === '@hugocxl/sounds')) {
200
+ for (const m of text.matchAll(/\bplay\(\s*['"]([^'"]+)['"]/g)) {
201
+ if (!k.sounds.has(m[1])) report('unknown-sound', `There is no sound named "${m[1]}". The sounds are ${[...k.sounds].join(', ')}.`, m.index);
202
+ }
203
+ for (const m of text.matchAll(/\bhaptic\(\s*['"]([^'"]+)['"]/g)) {
204
+ if (!k.haptics.has(m[1])) report('unknown-sound', `There is no haptic named "${m[1]}". The haptics are ${[...k.haptics].join(', ')}.`, m.index);
205
+ }
206
+ }
207
+ if (k.designSystem) {
208
+ if (CODE.has(ext)) {
209
+ for (const m of text.matchAll(PALETTE)) {
210
+ report('tailwind-palette', `"${m[0]}" uses Tailwind's default palette. Use the design system's token utilities (bg-canvas, text-ink, text-muted, border-rule…).`, m.index);
211
+ }
212
+ }
213
+ if (STYLES.has(ext)) {
214
+ for (const m of text.matchAll(RAW_COLOR)) {
215
+ const { line, column } = lineAt(text, m.index);
216
+ const declaration = lines[line - 1].slice(0, column - 1).split(/[;{]/).pop();
217
+ if (/^\s*--[\w-]+\s*:/.test(declaration)) continue; // defining a custom property is how tokens are made
218
+ report('raw-color', `"${m[0]}" is a raw color. Use a design-system token such as var(--ds-ink) or var(--ds-muted).`, m.index);
219
+ }
220
+ }
221
+ }
222
+ return findings;
223
+ }
224
+
225
+ function checkManifest(root) {
226
+ const manifest = readManifest(root);
227
+ const findings = [];
228
+ for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
229
+ for (const name of Object.keys(manifest[field] ?? {})) {
230
+ if (FOREIGN_ICON_PACKAGES.some(re => re.test(name))) {
231
+ findings.push({ file: 'package.json', line: 1, column: 1, rule: 'foreign-icons', message: `${name} is another icon library. Remove it and use @hugocxl/icons.` });
232
+ }
233
+ }
234
+ }
235
+ return findings;
236
+ }
237
+
238
+ function checkAgentFiles(root) {
239
+ const { write, remove } = plan(root);
240
+ return [
241
+ ...write.map(({ path, created }) => ({ file: path, line: 1, column: 1, rule: 'agent-files', message: created ? 'is missing. Run npx @hugocxl/ai sync.' : 'is out of date with the installed libraries. Run npx @hugocxl/ai sync.' })),
242
+ ...remove.map(({ path }) => ({ file: path, line: 1, column: 1, rule: 'agent-files', message: 'belongs to a library or version that is no longer installed. Run npx @hugocxl/ai sync.' })),
243
+ ];
244
+ }
245
+
246
+ /** Run every rule over the project. Findings carry their level after the project's settings. */
247
+ export async function check(root, { files } = {}) {
248
+ const config = settings(root);
249
+ const levels = Object.fromEntries(Object.entries(RULES).map(([rule, { level }]) => [rule, config.rules[rule] ?? level]));
250
+ const knowledge = await loadKnowledge(root, libraries(root));
251
+ const findings = [...checkAgentFiles(root), ...checkManifest(root)];
252
+ const list = files ?? sourceFiles(root, config.ignore);
253
+ for (const file of list) {
254
+ const text = readFileSync(join(root, file), 'utf8');
255
+ for (const finding of checkText(file, text, knowledge)) findings.push({ file: file.split(sep).join('/'), ...finding });
256
+ }
257
+ return {
258
+ files: list.length,
259
+ findings: findings
260
+ .map(finding => ({ ...finding, level: levels[finding.rule] }))
261
+ .filter(finding => finding.level !== 'off')
262
+ .sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column),
263
+ };
264
+ }
265
+
package/src/cli.mjs ADDED
@@ -0,0 +1,104 @@
1
+ import { relative } from 'node:path';
2
+ import { check, RULES } from './check.mjs';
3
+ import { findRoot, stackVersion } from './project.mjs';
4
+ import { SKILL_DIRS, sync } from './sync.mjs';
5
+
6
+ const HELP = `Usage: npx @hugocxl/ai <command> [options]
7
+
8
+ Set up a project so every AI agent uses the @hugocxl stack the same way.
9
+
10
+ Commands:
11
+ init Set up the agent files: a stack section in AGENTS.md, a CLAUDE.md that
12
+ imports it, and the skills of the installed libraries
13
+ sync Update the agent files after installing or upgrading a library
14
+ check Check the project follows the stack (exit 1 on errors)
15
+
16
+ Options:
17
+ --cwd <dir> Run in another directory (default: the nearest package.json)
18
+ --json check: print findings as JSON
19
+ --strict check: treat warnings as errors
20
+ -v, --version Print the version
21
+ -h, --help Show this help
22
+
23
+ Rules for check (set one to "off", "warning" or "error" under "stack.rules" in
24
+ package.json, and skip paths with "stack.ignore" globs or a stack-ignore comment):
25
+ ${Object.entries(RULES).map(([rule, { level, summary }]) => ` ${rule.padEnd(17)} ${level.padEnd(8)} ${summary}`).join('\n')}
26
+ `;
27
+
28
+ function parse(argv) {
29
+ const options = { command: null, cwd: process.cwd(), json: false, strict: false };
30
+ for (let i = 0; i < argv.length; i++) {
31
+ const arg = argv[i];
32
+ if (arg === '--cwd') options.cwd = argv[++i];
33
+ else if (arg === '--json') options.json = true;
34
+ else if (arg === '--strict') options.strict = true;
35
+ else if (arg === '-h' || arg === '--help') options.command = 'help';
36
+ else if (arg === '-v' || arg === '--version') options.command = 'version';
37
+ else if (!arg.startsWith('-') && !options.command) options.command = arg;
38
+ else throw new Error(`Unknown option: ${arg}`);
39
+ }
40
+ return options;
41
+ }
42
+
43
+ function printSync(root, result, log) {
44
+ for (const { path, created } of result.write) log(` ${created ? 'created' : 'updated'} ${path}`);
45
+ for (const { path } of result.remove) log(` removed ${path}`);
46
+ if (!result.write.length && !result.remove.length) log(' Agent files are already up to date.');
47
+ const missing = result.libs.filter(library => !library.installed);
48
+ const old = result.libs.filter(library => library.installed && !library.skillDir);
49
+ const installed = result.libs.filter(library => library.skillDir).map(library => `${library.package}@${library.version}`);
50
+ if (installed.length) log(`\nSkills from ${installed.join(', ')} are in ${SKILL_DIRS.join(' and ')}.`);
51
+ if (old.length) log(`\nUpgrade to get their skills: npm install ${old.map(library => `${library.package}@latest`).join(' ')}`);
52
+ if (missing.length) log(`\nNot installed yet: npm install ${missing.map(library => library.package).join(' ')}`);
53
+ }
54
+
55
+ export async function main(argv, { log = console.log, error = console.error } = {}) {
56
+ let options;
57
+ try {
58
+ options = parse(argv);
59
+ } catch (err) {
60
+ error(err.message);
61
+ error(HELP);
62
+ return 2;
63
+ }
64
+ const root = findRoot(options.cwd);
65
+
66
+ switch (options.command) {
67
+ case 'version':
68
+ log(stackVersion());
69
+ return 0;
70
+ case null:
71
+ case 'help':
72
+ log(HELP);
73
+ return options.command ? 0 : 2;
74
+ case 'init':
75
+ case 'sync': {
76
+ log(`@hugocxl/ai ${options.command} in ${relative(process.cwd(), root) || '.'}`);
77
+ printSync(root, sync(root), log);
78
+ if (options.command === 'init') {
79
+ log('\nCommit AGENTS.md, CLAUDE.md and the skill folders. Before finishing any task, agents run:');
80
+ log(' npx @hugocxl/ai check');
81
+ }
82
+ return 0;
83
+ }
84
+ case 'check': {
85
+ const { files, findings } = await check(root);
86
+ const level = finding => (options.strict && finding.level === 'warning' ? 'error' : finding.level);
87
+ const errors = findings.filter(finding => level(finding) === 'error').length;
88
+ const warnings = findings.length - errors;
89
+ if (options.json) {
90
+ log(JSON.stringify({ files, errors, warnings, findings: findings.map(finding => ({ ...finding, level: level(finding) })) }, null, 2));
91
+ } else {
92
+ for (const finding of findings) {
93
+ log(`${finding.file}:${finding.line}:${finding.column} ${level(finding).padEnd(7)} ${finding.message} (${finding.rule})`);
94
+ }
95
+ log(`${findings.length ? '\n' : ''}Checked ${files} file${files === 1 ? '' : 's'}: ${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'}.`);
96
+ }
97
+ return errors ? 1 : 0;
98
+ }
99
+ default:
100
+ error(`Unknown command: ${options.command}\n`);
101
+ error(HELP);
102
+ return 2;
103
+ }
104
+ }
@@ -0,0 +1,65 @@
1
+ // Locate a project and the @hugocxl libraries installed in it.
2
+ import { existsSync, readFileSync } from 'node:fs';
3
+ import { createRequire } from 'node:module';
4
+ import { dirname, join, resolve } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+
7
+ /** The four libraries, in the order agents should read them. */
8
+ export const LIBRARIES = [
9
+ { id: 'design-system', package: '@hugocxl/design-system', need: 'Type, color, spacing, layout, pages and components' },
10
+ { id: 'icons', package: '@hugocxl/icons', need: 'Icons that label actions and kinds' },
11
+ { id: 'vectors', package: '@hugocxl/vectors', need: 'Illustrations that explain an idea or a state' },
12
+ { id: 'sounds', package: '@hugocxl/sounds', need: 'Sound and haptic feedback for direct actions' },
13
+ ];
14
+
15
+ /** This package's own root, where the `stack` skill and the templates live. */
16
+ export const STACK_ROOT = fileURLToPath(new URL('../', import.meta.url));
17
+
18
+ export const stackVersion = () => JSON.parse(readFileSync(join(STACK_ROOT, 'package.json'), 'utf8')).version;
19
+
20
+ /** The nearest directory at or above `cwd` that has a package.json, or `cwd` itself. */
21
+ export function findRoot(cwd = process.cwd()) {
22
+ let dir = resolve(cwd);
23
+ for (;;) {
24
+ if (existsSync(join(dir, 'package.json'))) return dir;
25
+ const parent = dirname(dir);
26
+ if (parent === dir) return resolve(cwd);
27
+ dir = parent;
28
+ }
29
+ }
30
+
31
+ export function readManifest(root) {
32
+ try {
33
+ return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
34
+ } catch {
35
+ return {};
36
+ }
37
+ }
38
+
39
+ /** The directory of an installed package as the project resolves it, or null. */
40
+ export function packageDir(root, name) {
41
+ // Node caches resolutions per process, so confirm the file is still there.
42
+ try {
43
+ const manifest = createRequire(join(root, 'package.json')).resolve(`${name}/package.json`);
44
+ return existsSync(manifest) ? dirname(manifest) : null;
45
+ } catch {
46
+ return null;
47
+ }
48
+ }
49
+
50
+ /** Every library with its install state: `dir`, `version` and `skillDir` when installed. */
51
+ export function libraries(root) {
52
+ return LIBRARIES.map(library => {
53
+ const dir = packageDir(root, library.package);
54
+ if (!dir) return { ...library, installed: false };
55
+ const { version } = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
56
+ const skillDir = join(dir, 'skills', library.id);
57
+ return { ...library, installed: true, dir, version, skillDir: existsSync(join(skillDir, 'SKILL.md')) ? skillDir : null };
58
+ });
59
+ }
60
+
61
+ /** The project's `stack` settings from package.json. */
62
+ export function settings(root) {
63
+ const config = readManifest(root).stack ?? {};
64
+ return { rules: config.rules ?? {}, ignore: config.ignore ?? [] };
65
+ }
package/src/sync.mjs ADDED
@@ -0,0 +1,110 @@
1
+ // Write and verify the agent files a project gets from the stack: a managed section in
2
+ // AGENTS.md, a CLAUDE.md that imports it, and a copy of each installed library's skill.
3
+ import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
4
+ import { dirname, join, relative } from 'node:path';
5
+ import { LIBRARIES, STACK_ROOT, libraries } from './project.mjs';
6
+
7
+ /** Where skills are copied. `.agents/skills` is read by most agents; Claude Code reads `.claude/skills`. */
8
+ export const SKILL_DIRS = ['.agents/skills', '.claude/skills'];
9
+ export const BEGIN = '<!-- @hugocxl/ai:begin — managed by `npx @hugocxl/ai sync`. Edit outside these markers. -->';
10
+ export const END = '<!-- @hugocxl/ai:end -->';
11
+ const MANAGED_IDS = ['stack', ...LIBRARIES.map(library => library.id)];
12
+
13
+ function filesIn(dir, base = dir) {
14
+ return readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
15
+ const path = join(dir, entry.name);
16
+ return entry.isDirectory() ? filesIn(path, base) : [relative(base, path)];
17
+ });
18
+ }
19
+
20
+ /** The managed section of AGENTS.md for these libraries. */
21
+ export function agentsSection(libs) {
22
+ const rows = libs.map(library => {
23
+ const use = library.installed ? `\`${library.package}\`` : `\`${library.package}\` (not installed: \`npm install ${library.package}\`)`;
24
+ const skill = library.skillDir ? `\`${SKILL_DIRS[0]}/${library.id}\`` : library.installed ? 'upgrade the package to get its skill' : '—';
25
+ return `| ${library.need} | ${use} | ${skill} |`;
26
+ });
27
+ const body = readFileSync(join(STACK_ROOT, 'templates/AGENTS.md'), 'utf8')
28
+ .replace('{{libraries}}', rows.join('\n'))
29
+ .replaceAll('{{skillsDir}}', SKILL_DIRS[0]);
30
+ return `${BEGIN}\n${body.trimEnd()}\n${END}`;
31
+ }
32
+
33
+ function pruneEmpty(dir) {
34
+ if (!existsSync(dir) || !lstatSync(dir).isDirectory()) return;
35
+ for (const entry of readdirSync(dir)) pruneEmpty(join(dir, entry));
36
+ if (readdirSync(dir).length === 0) rmSync(dir, { recursive: true });
37
+ }
38
+
39
+ /** AGENTS.md with its managed section added or replaced, keeping everything else. */
40
+ export function withSection(current, section) {
41
+ if (current == null) return `# Agent instructions\n\n${section}\n`;
42
+ const start = current.indexOf(BEGIN.slice(0, 26));
43
+ const end = current.indexOf(END);
44
+ if (start >= 0 && end > start) return current.slice(0, start) + section + current.slice(end + END.length);
45
+ return `${current.trimEnd()}\n\n${section}\n`;
46
+ }
47
+
48
+ /** CLAUDE.md that imports AGENTS.md, keeping anything already in it. */
49
+ export function withImport(current) {
50
+ if (current == null) return '@AGENTS.md\n';
51
+ if (/^@AGENTS\.md\s*$/m.test(current)) return current;
52
+ return `@AGENTS.md\n\n${current}`;
53
+ }
54
+
55
+ /** Every file the stack manages in `root`, with the content it should have. */
56
+ export function desiredFiles(root) {
57
+ const libs = libraries(root);
58
+ const files = new Map();
59
+ const read = path => (existsSync(path) ? readFileSync(path, 'utf8') : null);
60
+
61
+ files.set('AGENTS.md', withSection(read(join(root, 'AGENTS.md')), agentsSection(libs)));
62
+ const claude = join(root, 'CLAUDE.md');
63
+ if (!(existsSync(claude) && lstatSync(claude).isSymbolicLink())) files.set('CLAUDE.md', withImport(read(claude)));
64
+
65
+ const sources = [{ id: 'stack', skillDir: join(STACK_ROOT, 'skills/stack') }, ...libs.filter(library => library.skillDir)];
66
+ for (const base of SKILL_DIRS) {
67
+ for (const { id, skillDir } of sources) {
68
+ for (const file of filesIn(skillDir)) files.set(join(base, id, file), readFileSync(join(skillDir, file)));
69
+ }
70
+ }
71
+ return { libs, files };
72
+ }
73
+
74
+ /**
75
+ * Compare the project with what the stack wants. Returns the files to write and the files to
76
+ * delete (managed skill files whose library or source file is gone).
77
+ */
78
+ export function plan(root) {
79
+ const { libs, files } = desiredFiles(root);
80
+ const write = [];
81
+ for (const [path, content] of files) {
82
+ const target = join(root, path);
83
+ const current = existsSync(target) ? readFileSync(target) : null;
84
+ if (!current || !current.equals(Buffer.from(content))) write.push({ path, content, created: !current });
85
+ }
86
+ const remove = [];
87
+ for (const base of SKILL_DIRS) {
88
+ for (const id of MANAGED_IDS) {
89
+ const dir = join(root, base, id);
90
+ if (!existsSync(dir)) continue;
91
+ for (const file of filesIn(dir)) {
92
+ const path = join(base, id, file);
93
+ if (!files.has(path)) remove.push({ path });
94
+ }
95
+ }
96
+ }
97
+ return { libs, write, remove };
98
+ }
99
+
100
+ /** Bring the project's agent files up to date. */
101
+ export function sync(root) {
102
+ const result = plan(root);
103
+ for (const { path, content } of result.write) {
104
+ mkdirSync(dirname(join(root, path)), { recursive: true });
105
+ writeFileSync(join(root, path), content);
106
+ }
107
+ for (const { path } of result.remove) rmSync(join(root, path));
108
+ for (const base of SKILL_DIRS) for (const id of MANAGED_IDS) pruneEmpty(join(root, base, id));
109
+ return result;
110
+ }
@@ -0,0 +1,18 @@
1
+ ## The @hugocxl stack
2
+
3
+ This project builds its interface with the @hugocxl stack. Follow it exactly, so every agent
4
+ working here produces the same result.
5
+
6
+ | Need | Use | Skill |
7
+ | --- | --- | --- |
8
+ {{libraries}}
9
+
10
+ 1. Read `{{skillsDir}}/stack/SKILL.md` before any interface work, then the skill of each
11
+ library the task touches.
12
+ 2. Take icons only from `@hugocxl/icons`, illustrations only from `@hugocxl/vectors`,
13
+ interface sounds only from `@hugocxl/sounds`, and every color, size, space and font from
14
+ `@hugocxl/design-system` tokens. Never add another icon set, illustration, UI kit, theme or
15
+ sound library, and never use emoji or symbol characters as icons.
16
+ 3. Never guess an icon or vector name. Find it with the search script in its skill.
17
+ 4. Before you finish, run `npx @hugocxl/ai check` and fix every error.
18
+ 5. After upgrading a library, run `npx @hugocxl/ai sync` and commit the updated skills.