mobile-shadcn-conventions
How the Agenta mobile app (web/mobile) installs and extends shadcn/ui registry components, themes them via the palette token bridge, and uses Vercel AI Elements. Use when adding UI components under web/mobile, changing theme colors, editing components.json or globals.css, or building chat UI with AI Elements.
git clone --depth 1 https://github.com/Agenta-AI/agenta /tmp/mobile-shadcn-conventions && cp -r /tmp/mobile-shadcn-conventions/.agents/skills/mobile-shadcn-conventions ~/.claude/skills/mobile-shadcn-conventionsSKILL.md
# Mobile shadcn conventions `web/mobile` uses shadcn/ui on Tailwind v4 with CSS variables. No antd, ever. ## Installing registry components - Always install via the CLI from `web/mobile/`: `pnpm dlx shadcn@latest add <component>` (e.g. `button`, `sheet`, `dialog`, `command`, `skeleton`, `input`). - Components land in `src/components/ui/` (aliases in `components.json`). They are owned code: you may adapt them, but keep diffs minimal and expressed in semantic tokens so upstream refreshes stay cheap. - The CLI adds any peer deps (e.g. `@radix-ui/react-slot`) to `web/mobile/package.json` — commit the manifest and `web/pnpm-lock.yaml` changes together with the component. - Never copy component source from the shadcn website by hand; the CLI resolves the Tailwind v4 variant correctly. - Installing a shadcn component that references a NEW token (e.g. `bg-sidebar`, `chart-*`) requires extending VARS in `scripts/generate-shadcn-tokens.ts` + the `@theme inline` map in `globals.css` first — Tailwind v4 silently generates nothing for unmapped tokens. ## Theming — the token bridge - shadcn variables (`--background`, `--primary`, ...) are NOT hand-maintained. They are generated into `src/styles/theme.generated.css` from `web/oss/src/styles/theme/palette.ts` by `scripts/generate-shadcn-tokens.ts`. - To change a color: edit `palette.ts` (if the design-system value is wrong) or the ROLE MAP in the script (if the mapping is wrong), then run `pnpm --filter @agenta/mobile generate:tokens` and commit the regenerated CSS. - Never edit `theme.generated.css` directly; never introduce raw hex values in components — if a needed role is missing, extend the bridge. - Dark mode is the `.dark` class on `<html>` (`@custom-variant dark` in `globals.css`), set pre-paint by the `_document.tsx` init script from the shared `agenta-theme` localStorage key. Both themes must be checked for every new surface. ## Extending components - Wrap, don't fork: feature-specific variants live in `src/features/*` as thin wrappers over `components/ui/*` primitives (cva variants where appropriate). - Use the `cn` util from `@/lib/utils` for all class merging. ## Vercel AI Elements (chat render layer, WP3b+) - AI Elements are shadcn registry components; install them the same way (`pnpm dlx shadcn@latest add <ai-elements registry item>`), landing in `src/components/ui/` / `src/components/ai-elements/` per the registry config. - They are the base of the chat skin (Conversation, Message, Response, Reasoning, Tool, PromptInput); behavior comes from `@agenta/chat` hooks — never re-implement orchestration inside a rendered component.
Helps add announcement cards to the sidebar banner system. Use when adding changelog entries, feature announcements, updates, or promotional banners to the Agenta sidebar. Handles both simple changelog entries and complex custom banners.
Playbook for adding a new coding-agent harness to Agenta (Codex, Hermes, Gemini, OpenCode, ...). Use when starting, planning, or reviewing a new-harness project. Covers the readiness audit of prior art, the spike-first milestone plan, the full integration-surface checklist, the per-harness variance axes to probe, and the process/communication contract with Mahmoud. Living document: every harness project appends its lessons to resources/LESSONS.md.
>-
Where to put frontend code (package vs app layer) and how to use the @agenta/* packages. Use when authoring or moving code in web/packages, choosing between @agenta/ui, @agenta/entities, @agenta/entity-ui, @agenta/shared, @agenta/playground, using molecules, loadable/runnable bridges, the EntityPicker, or writing package unit tests.
Use this skill to create and publish changelog announcements for new features, improvements, or bug fixes. This skill handles the complete workflow - creating detailed changelog documentation pages, adding sidebar announcement cards, and ensuring everything follows project standards. Use when the user mentions adding changelog entries, documenting new features, creating release notes, or announcing product updates.
Hard-won GitButler mechanics for multi-lane work in this repo — committing to a specific lane in a stack, spreading a pile of edits back across an existing stack, ordering a stack and setting PR bases, and recovering from a scrambled workspace. Use when working with stacked branches, when `but rub`/`but absorb`/`but commit --only` mis-routes a change, when a stack collapses or a commit lands on the wrong lane, or when a hunk gets dropped. Not needed for ordinary single-lane work.
Drive a researched and planned feature to a landed, tested change. Use after plan-feature has produced a docs/design/<project>/ workspace and the user says "implement it", "build the plan", "run the plan", or "let's ship this". Orchestrates refresh-plan, implement, review, a debug-local-deployment loop, and a test loop across the daytona / local-pi / claude x SDK / UI matrix, then documentation and a GitButler stacked branch. The orchestrator stays in the loop and spins narrow subagents for each phase.
Feature-folder layout, states/ convention, and data-flow rules for the Agenta mobile app (web/mobile). Use when creating or moving files under web/mobile, deciding where a component lives, adding a new feature or screen, or wiring data into mobile components.