feat(docs): publish Hopper as an agent Skill (#980)

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Alexandre Asselin <alexandre.asselin@workleap.com>

Author: 3 people

.github/workflows/ci.yml

@@ -50,6 +50,9 @@ jobs:
             -   name: Build AI docs and MCP server
                 run: pnpm build:mcp
 
+            -   name: Build the agent Skill
+                run: pnpm build:skills
+
             -   name: Lint
                 run: pnpm lint
 

AGENTS.md

@@ -67,6 +67,12 @@ Path patterns: packages/components/src/**/*.tsx
 
 ## Skills
 
+Hopper also publishes a consumer-facing agent Skill generated from `apps/docs` — see
+`apps/docs/ai-pipeline/CONTRIBUTING.md` and [ADR 0002](docs/adr/0002-hopper-agent-skill.md).
+Component and token content edits now propagate to three surfaces: the documentation site, the MCP
+server, and that published Skill. It is a build artifact and is not checked in, so it does not
+appear in the table below, which lists the skills used when working _in_ this repository.
+
 | Skill                 | When to use                                                                |
 | --------------------- | -------------------------------------------------------------------------- |
 | `update-tokens`       | Add, update, delete, or deprecate design tokens                            |

apps/docs/.gitignore

@@ -41,3 +41,6 @@ next-env.d.ts
 
 #AI docs
 /public/ai-docs
+
+#Generated agent skills, served at /.well-known/skills
+/public/agent-skills

apps/docs/ai-pipeline/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to AI Documentation Configuration
 
-This guide explains how to configure the AI documentation system by adding new routes in the `config.ts` file.
+This guide explains how to configure the AI documentation system by adding new routes in the `ai-docs.config.tsx` file.
 
 ## Overview
 
@@ -11,7 +11,7 @@ The AI documentation system uses a bidirectional mapping configuration that serv
 
 ## Configuration Structure
 
-The main configuration is in `config.ts` and follows this structure:
+The main configuration is in `ai-docs.config.tsx` and follows this structure:
 
 ```typescript
 export const aiDocsConfig: AiDocsConfig = {
@@ -398,3 +398,139 @@ The transformation ensures that:
 2. System reverse-lookups the configuration
 3. Finds matching route with `serve.at` or route key (through the [txt](/apps/docs/app/txt/) router)
 4. Serves the corresponding generated content
+
+## Skills
+
+On top of the AI docs, this pipeline publishes an [agent Skill](https://www.npmjs.com/package/skills)
+at `https://hopper.workleap.design/.well-known/skills`, installed with
+`npx skills add https://hopper.workleap.design`.
+
+Skill generation is a **second stage that composes `dist/ai-docs`** — it never renders MDX again.
+`docs#build:skills` therefore declares `docs#build:ai-docs` as a Turbo dependency, so one command
+is enough:
+
+```bash
+pnpm build:skills   # ~1s once the AI docs are cached; re-run freely
+```
+
+`docs#build` also depends on `docs#build:skills`, which is what makes the single
+`turbo run build --filter=./apps/docs` command in `netlify.toml` publish the skill.
+
+Output lands in `dist/skills` and is copied to `public/agent-skills` (gitignored, like
+`public/ai-docs`).
+
+### Files
+
+| File                                                                                                  | Role                                                                                                    |
+| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `skills.config.ts`                                                                                    | What the skill contains. The only file most changes touch.                                              |
+| `skillsTypes.ts`                                                                                      | Entry types and their guards.                                                                           |
+| `templates/skills/hopper/**`                                                                          | Hand-authored markdown: `SKILL.header.md`, workflows, and the guides that have no generated equivalent. |
+| `skill-scripts/**`                                                                                    | Sources for the scripts bundled into the skill.                                                         |
+| `../scripts/buildSkills.ts`                                                                           | Orchestrator.                                                                                           |
+| `../scripts/ai-utils/{copySkillFiles,generateSkillIndex,generateSkillManifest,bundleSkillScripts}.ts` | The stages it runs.                                                                                     |
+| `../scripts/checkSkillsConfig.ts`                                                                     | Runs as `pnpm --filter=docs test`; see below.                                                           |
+
+### Entry types
+
+`skills.config.ts` `files` accepts three shapes, distinguished by which key is present:
+
+```ts
+// copy — `from` is a glob under dist/ai-docs. A `to` ending in "/" keeps the source path
+// relative to the glob's literal prefix, so nested matches do not collapse together.
+{ from: "/components/usage/*.md", exclude: ["/components/usage/component-list.md"], to: "references/components/" }
+
+// copyTemplate — a hand-authored file, copied verbatim
+{ copyTemplate: "/ai-pipeline/templates/skills/hopper/workflows/build-app.md", to: "references/workflows/build-app.md" }
+
+// merge — a hand-authored template followed by generated content
+{ template: "/ai-pipeline/templates/skills/hopper/guides/validation-rules.md",
+  merge: ["/styled-system/escape-hatches.md"], to: "references/guides/validation-rules.md" }
+```
+
+`SKILL.md` is `templates/skills/hopper/SKILL.header.md` plus a generated "Documentation structure"
+index built from what actually landed on disk. Section descriptions come from each file's first
+paragraph, or from `description` in the config. Use `style: "names"` for long tails such as
+components — a bullet per file would triple the size of `SKILL.md`.
+
+### Scripts share code with the MCP server
+
+The skill's three scripts are **not** reimplementations. Each bundles a service straight out of
+`apps/mcp-server` with esbuild, so a logic change there reaches both surfaces at the next build:
+
+| Script                             | MCP tool               | Bundled from                    |
+| ---------------------------------- | ---------------------- | ------------------------------- |
+| `scripts/validate-hopper-code.mjs` | `validate_hopper_code` | `src/services/validatorService` |
+| `scripts/search-tokens.mjs`        | `get_design_tokens`    | `src/services/tokensService`    |
+| `scripts/search-icons.mjs`         | `get_icons`            | `src/services/iconsService`     |
+
+The entry points in `skill-scripts/` are thin CLI wrappers — argument parsing and output
+formatting only. Keep them that way; anything resembling business logic belongs in the service, so
+both surfaces get it.
+
+Two things are swapped at bundle time, via `aliases` in `skills.config.ts`:
+
+- `@docs/ai` and the `env` module (`dataAliases`) → the services read the skill's own `references/`
+  instead of a deployed docs folder. This is why the skill mirrors the AI docs layout there.
+- `@typescript-eslint/parser` → `validatorParser.ts`, only for the validator. Bundling the real
+  parser would pull in `typescript`, several times the whole skill budget.
+
+To verify parity after touching a service, run the script and the matching MCP tool on the same
+input and diff them.
+
+### The skill ships as one archive
+
+`buildSkills.ts` writes both the loose files under `dist/skills/hopper/**` _and_ a single
+`dist/skills/hopper.tar.gz`, and `index.json` advertises only the archive, using the 0.2.0
+discovery schema with a sha256 digest.
+
+That is deliberate. The `skills` CLI's per-file path (`fetchLegacySkillByEntry`) fires one `fetch`
+per advertised file with **no concurrency limit** and swallows every failure — `catch {}` returns
+`null` and the file is silently skipped, with no error and no retry. At this skill's size that
+reliably loses files: measured 263-317 of 326 across runs, with `scripts/` missing every time
+because it sorts last and holds the largest files. Nothing in the output tells you.
+
+With the archive the client does one request and verifies a digest, so an install is either
+complete or a visible failure. It is also ~10x less to transfer (0.52 MB compressed vs 4.8 MB).
+
+The loose files stay published because they are handy to `curl` and cost nothing extra. If you
+change what the skill contains, the archive and digest regenerate automatically — never hand-edit
+`index.json`.
+
+### Constraints to respect
+
+- **Exactly one skill.** The `skills` CLI demands an explicit `@selector` when a host advertises
+  more than one, which would break the bare `npx skills add https://hopper.workleap.design`.
+- **A 5.5 MB budget** (`maxTotalBytes`). The build fails above it. Trim an entry rather than raising
+  the ceiling. The heavy things deliberately left out are `components/api/full` (7 MB),
+  `llms-full.md`, every `*/index.md` merge artifact, and `changelogs.md`.
+- **`references/tokens/maps/**`, `references/icons/data.json` and
+  `references/styled-system/unsafe-props-data.json` must keep their AI docs paths.** The bundled
+  scripts reach them through the generated `files` index, so renaming them breaks the scripts
+  silently. The whole `tokens/maps` tree ships for the same reason: `getTokenMapFiles` resolves a
+  file per category, so dropping the per-category files would make every narrower `--category`
+  throw.
+- **`/.well-known/skills/**` is aliased onto `public/agent-skills` in two places, and both are
+  needed.** `netlify.toml` `[[redirects]]` (with `force = true`) handles production on the CDN;
+  the `beforeFiles` rewrite in `next.config.js` handles `next dev`, which is what makes
+  `npx skills add http://localhost:3000` work. `@netlify/plugin-nextjs` does not honour
+  `beforeFiles` for these paths — without the Netlify rules, `/.well-known/skills/**/*.md` is
+  claimed by the `/:path*.:ext(txt|md)` rule in `afterFiles` and the `/txt` handler answers 400.
+  CORS headers are likewise declared in both files, since Next's `headers()` does not apply to a
+  CDN-resolved rewrite.
+
+### Testing a change
+
+`pnpm --filter=docs test` runs `checkSkillsConfig.ts`, which asserts every `from` pattern still
+corresponds to a route in `ai-docs.config.tsx`, that templates and script entry points exist, and
+that each index section has content. It needs no build output and runs in PR CI.
+
+Then, from a scratch directory outside the repo:
+
+```bash
+pnpm doc:start
+cd $(mktemp -d) && npx skills add http://localhost:3000
+```
+
+Install from a scratch directory — running it inside `wl-hopper` would write into `.claude/skills`,
+which is where this repo's own authoring skills live.

apps/docs/ai-pipeline/skill-scripts/searchIcons.ts

@@ -0,0 +1,68 @@
+/**
+ * CLI entry point for the Hopper skill's icon search.
+ *
+ * Bundles the MCP server's `iconsService` verbatim — same Fuse.js configuration, same weights and
+ * threshold — so the skill and the `get_icons` tool return identical results and a change to the
+ * search logic reaches both at build time. Only the data path is swapped (see validatorEnv.ts).
+ *
+ * Usage:
+ *   node scripts/search-icons.mjs add "new product"
+ *   node scripts/search-icons.mjs --type rich --limit 5 delete
+ *   node scripts/search-icons.mjs --type standard          # no query: list them all
+ *
+ * Each argument is one query, and a query may hold several space-separated keywords.
+ */
+import { type IconType, IconTypes, getIcons } from "../../../mcp-server/src/services/iconsService.ts";
+
+function parseArguments(argv: string[]) {
+    const queries: string[] = [];
+    let type: IconType = "all";
+    let limit: number | undefined;
+
+    for (let index = 0; index < argv.length; index++) {
+        const argument = argv[index];
+
+        if (argument === "--type") {
+            const value = argv[++index];
+            if (!IconTypes.includes(value as IconType)) {
+                throw new Error(`--type must be one of: ${IconTypes.join(", ")}`);
+            }
+            type = value as IconType;
+        } else if (argument === "--limit") {
+            limit = Number(argv[++index]);
+            if (!Number.isFinite(limit) || limit <= 0) {
+                throw new Error("--limit must be a positive number.");
+            }
+        } else if (argument === "--help" || argument === "-h") {
+            console.log("Usage: node scripts/search-icons.mjs [--type standard|rich|all] [--limit N] <query...>");
+            process.exit(0);
+        } else {
+            queries.push(argument);
+        }
+    }
+
+    return { queries, type, limit };
+}
+
+async function main() {
+    const { queries, type, limit } = parseArguments(process.argv.slice(2));
+    const results = await getIcons(queries, type, limit);
+
+    for (const [query, icons] of Object.entries(results)) {
+        console.log(`\n${query} — ${icons.length} match${icons.length === 1 ? "" : "es"}`);
+
+        if (icons.length === 0) {
+            console.log("  (nothing matched; try a synonym, the keywords field often differs from the name)");
+            continue;
+        }
+
+        for (const icon of icons) {
+            console.log(`  ${icon.name}  [${icon.type}]  ${icon.description}`);
+        }
+    }
+}
+
+main().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(2);
+});

apps/docs/ai-pipeline/skill-scripts/searchTokens.ts

@@ -0,0 +1,123 @@
+/**
+ * CLI entry point for the Hopper skill's design token lookup.
+ *
+ * Bundles the MCP server's `tokensService` verbatim — same filtering, same brief/full output
+ * shapes — so the skill and the `get_design_tokens` tool return identical results and a change to
+ * the lookup logic reaches both at build time. Only the data path is swapped (see validatorEnv.ts).
+ *
+ * Usage:
+ *   node scripts/search-tokens.mjs --name hop-neutral-text
+ *   node scripts/search-tokens.mjs --css 16px --css "#3C3C3C" --with-css-values
+ *   node scripts/search-tokens.mjs --prop backgroundColor --category semantic-color
+ *   node scripts/search-tokens.mjs --theme sharegate --scheme dark --name hop-primary-surface
+ *
+ * With no filter it prints the whole category, which is large — pass at least one of
+ * --name / --css / --prop unless you actually want the full map.
+ */
+import {
+    type ColorScheme,
+    ColorSchemes,
+    type Theme,
+    Themes,
+    TokenCategories,
+    type TokenCategory
+} from "../../../mcp-server/src/config/constants.ts";
+import { getDesignTokens } from "../../../mcp-server/src/services/tokensService.ts";
+import { DESIGN_TOKEN_PREFIXES_AND_SUFFIXES } from "../../../mcp-server/src/utils/tokenNameFormatter.ts";
+
+const USAGE = `Usage: node scripts/search-tokens.mjs [options]
+
+  --name <token>     Filter by Hopper token name, partial match (repeatable).
+                     Pass token names like "hop-neutral-text", not CSS values.
+  --css <value>      Filter by CSS value, fuzzy match (repeatable).
+                     Pass values like "16px", "#3C3C3C", "400".
+  --prop <prop>      Only categories usable with this style prop (repeatable).
+  --category <cat>   Default "all". One of:
+                     ${TokenCategories.join(", ")}
+  --theme <theme>    Default "workleap". One of: ${Themes.join(", ")}
+  --scheme <scheme>  Default "light". One of: ${ColorSchemes.join(", ")}
+  --with-css-values  Include each token's CSS value in the output.`;
+
+function parseArguments(argv: string[]) {
+    const names: string[] = [];
+    const cssValues: string[] = [];
+    const props: string[] = [];
+    let category: TokenCategory = "all";
+    let theme: Theme = "workleap";
+    let colorScheme: ColorScheme = "light";
+    let includeCssValues = false;
+
+    function oneOf<T extends string>(value: string, allowed: readonly T[], flag: string): T {
+        if (!allowed.includes(value as T)) {
+            throw new Error(`${flag} must be one of: ${allowed.join(", ")}`);
+        }
+
+        return value as T;
+    }
+
+    for (let index = 0; index < argv.length; index++) {
+        const argument = argv[index];
+
+        switch (argument) {
+            case "--name":
+                names.push(argv[++index]);
+                break;
+            case "--css":
+                cssValues.push(argv[++index]);
+                break;
+            case "--prop":
+                props.push(argv[++index]);
+                break;
+            case "--category":
+                category = oneOf(argv[++index], TokenCategories, "--category");
+                break;
+            case "--theme":
+                theme = oneOf(argv[++index], Themes, "--theme");
+                break;
+            case "--scheme":
+                colorScheme = oneOf(argv[++index], ColorSchemes, "--scheme");
+                break;
+            case "--with-css-values":
+                includeCssValues = true;
+                break;
+            case "--help":
+            case "-h":
+                console.log(USAGE);
+                process.exit(0);
+                break;
+            default:
+                throw new Error(`Unknown argument "${argument}".\n\n${USAGE}`);
+        }
+    }
+
+    return { names, cssValues, props, category, theme, colorScheme, includeCssValues };
+}
+
+async function main() {
+    const { names, cssValues, props, category, theme, colorScheme, includeCssValues } = parseArguments(
+        process.argv.slice(2)
+    );
+
+    const results = await getDesignTokens(category, names, cssValues, props, includeCssValues, theme, colorScheme);
+
+    if (results.length === 0) {
+        console.log(
+            "No tokens matched. Remember: --name takes token names, --css takes CSS values — they are not interchangeable."
+        );
+        process.exit(1);
+    }
+
+    for (const result of results) {
+        console.log(result.text);
+    }
+
+    // The same trailer the MCP tool appends, from the same constant, so the two cannot drift.
+    console.log(
+        `\n**Golden Rule**: Remove these substrings from 'token name' to get the correct 'prop value' instantly: ${DESIGN_TOKEN_PREFIXES_AND_SUFFIXES.join(", ")}`
+    );
+}
+
+main().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(2);
+});