From d5974ed2c9382efbd007658c1875ea49422404b6 Mon Sep 17 00:00:00 2001 From: Ruud Andriessen Date: Fri, 16 Oct 2026 13:52:55 +0200 Subject: [PATCH 1/2] feat(apollo-vertex): add a setup agent skill The skill sets up an app to use Apollo Vertex: peer dependencies, the stylesheet import, TanStack Intent with the Vertex skills allowed, and a rule in AGENTS.md that tells agents to follow the Vertex skills when they change UI. Assisted-by: Anthropic:claude-opus-5-5 --- packages/apollo-vertex/skills/setup/SKILL.md | 123 +++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 packages/apollo-vertex/skills/setup/SKILL.md diff --git a/packages/apollo-vertex/skills/setup/SKILL.md b/packages/apollo-vertex/skills/setup/SKILL.md new file mode 100644 index 000000000..3f8ebfacc --- /dev/null +++ b/packages/apollo-vertex/skills/setup/SKILL.md @@ -0,0 +1,123 @@ +--- +name: setup +description: > + Use when adding @uipath/apollo-vertex to a React app, or when an app that + already depends on it is missing the Vertex stylesheet or the agent skill + setup. Covers peer dependencies, importing the Vertex CSS, setting up + TanStack Intent so agents load the Vertex skills, and adding a rule to the + project's agent instructions. Not for building UI: load + use-vertex-components for that. +metadata: + purpose: > + Set up a React app to use Apollo Vertex and make its coding agents follow + the Vertex skills when they change UI. + type: lifecycle + library: '@uipath/apollo-vertex' +sources: + - 'UiPath/apollo-ui:packages/apollo-vertex/package.json' + - 'UiPath/apollo-ui:packages/apollo-vertex/styles/tailwind.css' + - 'UiPath/apollo-ui:apps/apollo-vertex/content/docs/getting-started.mdx' +--- + +# Set up Apollo Vertex + +Work from the project root and use the project's package manager (npm, pnpm, +yarn or bun) for every install. Do each step, then run the completion check. + +## 1. Install the package and its peers + +Install `@uipath/apollo-vertex` if the project doesn't have it yet. + +Then read `peerDependencies` in +`node_modules/@uipath/apollo-vertex/package.json` and make sure the app has +every package listed there, in a version that matches the range. Also install +every package listed in `peerDependenciesMeta`, even the ones marked optional +or missing from `peerDependencies`: the package entry imports them, so the +app's bundler fails to resolve the entry without them. + +- If the app already has a peer in a version outside the range, tell the user + about the conflict instead of upgrading it on your own. +- Some `@uipath` peers are not on the public npm registry. If installing one + fails with a 404 or an authentication error, stop and ask the user for access + to UiPath's package registry. Do not install look-alike packages from npm. +- If the app doesn't use Tailwind yet, set it up for the app's bundler with + Tailwind's own install guide: install the integration, such as + `@tailwindcss/vite`, and register it in the bundler config. Installing it is + not enough. + +## 2. Import the stylesheet + +Add these lines once to the app's main CSS file, the one that sets up Tailwind, +and remove its own `@import "tailwindcss";` line. If the app has no CSS file +yet, create one and import it from the app's entry point: + +```css +@import "@uipath/apollo-vertex/tailwind.css"; +@source "./"; +``` + +`tailwind.css` includes Tailwind, the Vertex theme and the classes the Vertex +components use. Keep `@source "./";` and adjust the path if the CSS file is not +next to the app's sources. Without it, Tailwind drops the classes used in the +app's own files. + +## 3. Set up TanStack Intent + +[TanStack Intent](https://tanstack.com/intent) finds the skills that ship in +`node_modules` and tells agents to load them. + +1. Add `@tanstack/intent` as a dev dependency. +2. Add this to the project's `package.json`. If an `intent.skills` list already + exists, add `@uipath/apollo-vertex` to it instead of replacing it: + + ```json + { + "intent": { + "skills": ["@uipath/apollo-vertex"] + } + } + ``` + +3. Run `intent install` through the package manager, for example + `npx intent install` or `pnpm exec intent install`. It writes a skill + loading block into `AGENTS.md`, or into another agent instructions file that + already has one. +4. Tell the user that you allowed agents to load the `@uipath/apollo-vertex` + skills, and that they can change this with `intent install --review` in a + terminal. + +Without the `intent.skills` entry, `intent install` stops and asks for +permissions in an interactive terminal, which an agent can't answer. + +## 4. Add the Vertex rule to the agent instructions + +`intent install` printed which file it wrote the skill loading block to. The +block starts with ``. Add this section to that same +file, right after the block: + +```markdown +## UI + +This app uses Apollo Vertex (`@uipath/apollo-vertex`) for all UI. Before +building or changing UI, run `intent list` and load the matching +`@uipath/apollo-vertex` skills, then follow them. +``` + +Write the `intent` command the way the skill loading block does, for example +`npm exec --no -- intent list`. + +If that file is `AGENTS.md`, make sure Claude Code reads it too: if the +project has a `CLAUDE.md`, it must import `AGENTS.md` with an `@AGENTS.md` line, +and if there is no `CLAUDE.md`, create one that contains only `@AGENTS.md`. + +## Completion + +- `intent list` shows `@uipath/apollo-vertex` with the `use-vertex-components` + skill. +- One agent instructions file has both the skill loading block and the UI + section. +- The app builds, and a Vertex component such as `Button` renders with Vertex + styling. + +Then tell the user what you changed, and load `use-vertex-components` before +building any UI. From b91003fbc6355c1853d542a0f59f7303a601b20a Mon Sep 17 00:00:00 2001 From: Ruud Andriessen Date: Fri, 16 Oct 2026 13:52:56 +0200 Subject: [PATCH 2/2] docs(apollo-vertex): set up Apollo Vertex with a copyable agent prompt The home page's "Start a solution" section now has a button that copies a short prompt: install the package, then load and follow the setup skill. Getting started shows the same prompt, drops the uip vss CLI steps and describes the setup skill under agent skills. Assisted-by: Anthropic:claude-opus-5-5 --- .../content/docs/_components/home.tsx | 61 ++++++++++++--- .../content/docs/getting-started.mdx | 77 +++++-------------- 2 files changed, 71 insertions(+), 67 deletions(-) diff --git a/apps/apollo-vertex/content/docs/_components/home.tsx b/apps/apollo-vertex/content/docs/_components/home.tsx index 8306615ca..f12c46348 100644 --- a/apps/apollo-vertex/content/docs/_components/home.tsx +++ b/apps/apollo-vertex/content/docs/_components/home.tsx @@ -1,5 +1,6 @@ "use client"; +import { Check, Copy } from "lucide-react"; import Link from "next/link"; import { useState } from "react"; import { Button } from "@/registry/button/button"; @@ -64,8 +65,29 @@ const sections = [ }, ]; +const agentPrompt = `Install @uipath/apollo-vertex with this project's package manager, then run: +npx @tanstack/intent@latest load @uipath/apollo-vertex#setup +Follow the skill it prints.`; + export function Home() { const [active, setActive] = useState(null); + const [copyState, setCopyState] = useState<"idle" | "copied" | "failed">( + "idle", + ); + + function handleCopy() { + if (!navigator.clipboard?.writeText) { + setCopyState("failed"); + return; + } + navigator.clipboard.writeText(agentPrompt).then( + () => { + setCopyState("copied"); + setTimeout(() => setCopyState("idle"), 1500); + }, + () => setCopyState("failed"), + ); + } return (
@@ -134,17 +156,36 @@ export function Home() { > Start a solution -

- The UiPath CLI creates a new vertical solution with{" "} - @uipath/vs-core already - installed and configured. +

+ Paste the prompt into Claude Code, Cursor or Copilot from your project + root. Your agent installs Apollo Vertex and sets it up. +

+
+ + + Or follow the setup guide yourself + +
+

+ {copyState === "failed" ? ( + <> + Your browser blocked the copy.{" "} + + Copy the prompt from the setup guide + + . + + ) : null}

- - Read the setup guide -
diff --git a/apps/apollo-vertex/content/docs/getting-started.mdx b/apps/apollo-vertex/content/docs/getting-started.mdx index 535809777..24f65bfcc 100644 --- a/apps/apollo-vertex/content/docs/getting-started.mdx +++ b/apps/apollo-vertex/content/docs/getting-started.mdx @@ -13,63 +13,19 @@ The `@uipath/vs-core` package provides everything you need to build data-driven - **TanStack Query Collections**: Ready-to-use data collections with built-in caching and reactivity - **TypeScript Types**: Full type safety for entities, processes, and configurations -## Getting Started +## Set up with your agent -To create a new vertical solution, you have two options: +Paste this prompt into your coding agent, such as Claude Code, Cursor or Copilot, from your project root: -**Option 1: Use the UiPath CLI (Recommended)** - -Install the `uipcli` tool and its vertical solutions plugin: - -```bash -npm install @uipath/cli @uipath/vss -``` - -After installing, you can run commands via `uip`. - -### `uip vss` commands - -Vertical Solutions plugin for managing UiPath Vertical Solutions. - -Also supports flags, for more info `uip vss --help` or `uip vss [command] --help`. - -Plugin docs: https://github.com/UiPath/cli/tree/main/packages/vertical-solutions-tool - -- **Initialize a new vertical solution** - -```bash -uip vss init -``` - -- **Scaffold a new vertical solution** - -```bash -uip vss scaffold +```text +Install @uipath/apollo-vertex with this project's package manager, then run: +npx @tanstack/intent@latest load @uipath/apollo-vertex#setup +Follow the skill it prints. ``` -- **Add an entity, process, or connection** +The `setup` skill installs the peer dependencies, imports the stylesheet, sets up [agent skills](#set-up-agent-skills) and tells your agent to follow them when it changes UI. To do the same steps yourself, follow the rest of this page. -```bash -uip vss add [path] -``` - -- **Sync a vertical solution** - -```bash -uip vss sync -``` - -- **Generate types for your vertical solution** - -```bash -uip vss generate -``` - -**Option 2: Fork the Template** - -Start with the [Vertical Solution Template](https://github.com/UiPath/vertical-solutions-template) for a pre-configured project structure. - -Both options give you a ready-to-use project with `@uipath/vs-core` already installed and configured. +To start a new vertical solution, fork the [Vertical Solution Template](https://github.com/UiPath/vertical-solutions-template). It comes with `@uipath/vs-core` installed and configured. ## Install Apollo Vertex @@ -96,10 +52,17 @@ import { Button, DataTable } from "@uipath/apollo-vertex"; Apollo Vertex ships [agent skills](https://agentskills.io) that tell coding agents such as Claude Code, Cursor and Copilot how to build UI with Apollo Vertex. For example, one skill tells the agent to use Vertex components instead of writing its own. [TanStack Intent](https://tanstack.com/intent) finds these skills in your `node_modules` and points your agent at them. -Run this once from your project root: +Apollo Vertex ships these skills: + +- `setup` sets up a project to use Apollo Vertex. The [agent prompt](#set-up-with-your-agent) loads it. +- `use-vertex-components` tells the agent to build UI from Vertex components. + +To set them up yourself, add TanStack Intent to your project and run its installer once from your project root: + + ```bash -npx @tanstack/intent@latest install +npx intent install ``` Run it in an interactive terminal. It asks which packages' skills your agent may load, saves your choice in `package.json`, and adds instructions to your agent config file (for example `AGENTS.md` or `CLAUDE.md`). Commit both files so everyone on the project gets the same setup. @@ -109,10 +72,10 @@ The skills are versioned with Apollo Vertex, so updating it updates them too. Yo To see the skills that are available, or to read one yourself: ```bash -npx @tanstack/intent@latest list -npx @tanstack/intent@latest load @uipath/apollo-vertex#use-vertex-components +npx intent list +npx intent load @uipath/apollo-vertex#use-vertex-components ``` ## Next Steps -After using the template or CLI, your project is pre-configured with everything you need. See the [Data Querying](/data-querying/loading-data) section to learn how to load and mutate data using the `useSolution` hook. +See the [Data Querying](/data-querying/loading-data) section to learn how to load and mutate data using the `useSolution` hook.