oma-frontend · first-fluke, oma — Claude Code skill: React, Next.js and shadcn/ui
oma-frontend is a Claude Code skill for building and editing frontend UI in React, Next.js, and TypeScript projects, including components, pages, styles, and client logic.
MIT ★ 1,472 updated 2026-10-29
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma@oh-my-agentWhat oma-frontend does
The skill handles UI assembly and edits in React 19+ and Next.js 16+ App Router projects. Inside: rules for Server and Client Components, shadcn/ui integration (reads components/ui but does not edit), design-token and i18n bindings, form validation via zod. Uses TailwindCSS v4, ahooks, es-toolkit, nuqs for URL state and TanStack Query for server state.
The project must be on Next.js 16 or later: proxy.ts for requests and auth instead of middleware.ts, which is banned here. The skill checks server/client boundaries, tracks responsive states and runs lint, typecheck and tests before handing off results. If the project lacks design tokens or i18n, it uses local patterns and documents assumptions.
For backend, DB migrations and auth server setup, install a different skill — this one works only on the browser layer.
What it helps with
- build a page or component in Next.js with Server Components
- wire up a shadcn/ui primitive and wrap it to match project tokens
- split client logic from server layout
- validate a form via zod and TanStack React Form
- integrate frontend with an API via TanStack Query
Example prompts for the agent
- Build a profile page in
app/profile/page.tsxwith Server Component and client form - Add a shadcn button to
components/shared/Header.tsxand bind it to design tokens - Create a signup form with zod validation and error messages in Russian
How to install oma-frontend
1Plugin marketplace
/plugin marketplace add first-fluke/oh-my-agent/plugin install oma@oh-my-agentThis installs the whole oma plugin with all its skills
2Skills CLI (Vercel)
npx skills add first-fluke/oh-my-agent --skill oma-frontend -a claude-code3Manually: put the files in place
~/.claude/skills/oma-frontend/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/oma-frontend/
1Skills CLI (Vercel)
npx skills add first-fluke/oh-my-agent --skill oma-frontend -a codex2Manually: put the files in place
.agents/skills/oma-frontend/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add first-fluke/oh-my-agent --skill oma-frontend -a cursor2Manually: put the files in place
.cursor/skills/oma-frontend/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install first-fluke/oh-my-agent benchmarks/runs/oma/.agents/skills/oma-frontend2Manually: put the files in place
.github/skills/oma-frontend/SKILL.md1Skills CLI (Vercel)
npx skills add first-fluke/oh-my-agent --skill oma-frontend -a gemini-cli2Platform CLI
gemini skills install https://github.com/first-fluke/oh-my-agent --path benchmarks/runs/oma/.agents/skills/oma-frontendManually: put the files in place
.devin/skills/oma-frontend/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about oma-frontend
How to install oma-frontend in Claude Code?
Run /plugin marketplace add first-fluke/oh-my-agent, then /plugin install oma@oh-my-agent. The skill will be in ~/.claude/skills/oma-frontend/SKILL.md.
What does oma-frontend do?
Builds and edits React/Next.js UI: pages, components, forms, styles. Tracks Server/Client boundaries, uses shadcn/ui, design tokens and i18n, runs lint and typecheck.
Why does oma-frontend require Next.js 16 or later?
The project uses proxy.ts for requests and auth. middleware.ts is banned, and the skill will not work with older Next.js versions where proxy.ts is unavailable.
Source text
SKILL.md · MIT
---
name: oma-frontend
description: Frontend specialist for React, Next.js, TypeScript with FSD-lite architecture, shadcn/ui, and design system alignment. Use for UI, component, page, layout, CSS, Tailwind, and shadcn work.
---
# Frontend Agent - UI/UX Specialist
## Scheduling
### Goal
Build, modify, and verify React/Next.js/TypeScript user interfaces that follow project architecture, design-system constraints, accessibility expectations, and existing frontend conventions.
### Intent signature
- User asks for UI, component, page, layout, CSS, Tailwind, shadcn, form, interaction, client state, or frontend API integration work.
- User needs browser-facing implementation in a React/Next.js TypeScript codebase.
### When to use
- Building user interfaces and components
- Client-side logic and state management
- Styling and responsive design
- Form validation and user interactions
- Integrating with backend APIs
### When NOT to use
- Backend API implementation → use Backend Agent
- Database access, migrations, or ORM setup → use Backend Agent
- Auth server setup (better-auth server library, DB adapters) → use Backend Agent
- Native mobile development → use Mobile Agent
### Expected inputs
- Target page, component, flow, or UI behavior
- Existing app structure, design tokens, component library, i18n files, and API contracts
- Acceptance criteria and target responsive states
### Expected outputs
- Frontend code changes in pages, components, hooks, styles, tests, or wrappers
- UI that respects project tokens, i18n, server/client boundaries, and accessibility expectations
- Verification results from relevant lint, typecheck, tests, or browser checks
### Dependencies
- React, Next.js, TypeScript, TailwindCSS v4, and `shadcn/ui`
- Project sources of truth such as `packages/design-tokens`, `packages/i18n`, and shared utilities
- `resources/execution-protocol.md`, `resources/checklist.md`, examples, snippets, and Tailwind rules
### Control-flow features
- Branches by server/client component boundary, responsive state, component library availability, and i18n/token requirements
- Reads and writes frontend codebase files
- May call shadcn registry tools or local verification commands
## Structural Flow
### Entry
1. Identify target route, component, state boundary, and design-system constraints.
2. Read existing patterns before adding components or utilities.
3. Determine whether work belongs in Server Components, Client Components, wrappers, hooks, or styles.
### Scenes
1. **PREPARE**: Load relevant project conventions, UI requirements, and acceptance criteria.
2. **ACQUIRE**: Inspect existing components, tokens, i18n keys, APIs, and shadcn availability.
3. **ACT**: Implement UI, state, styles, validation, and integration.
4. **VERIFY**: Run checklist, automated checks, and browser/responsive validation when applicable.
5. **FINALIZE**: Summarize changed UI behavior and verification.
### Transitions
- If a strict shadcn primitive exists, use or wrap it before creating generic markup.
- If UI text is user-facing and i18n exists, add strings through the i18n source of truth.
- If interaction or hooks are needed, mark the boundary as Client Component.
- If backend contracts are missing, coordinate with backend/API planning.
### Failure and recovery
- If design tokens or i18n sources are missing, state assumptions and follow existing local patterns.
- If verification fails, fix before handoff or report the blocker.
- If required shadcn registry access fails, use existing local components or document fallback.
### Exit
- Success: UI works across target responsive states and passes relevant checks.
- Partial success: missing assets, backend contracts, or verification gaps are explicit.
## Logical Operations
### Actions
| Action | SSL primitive | Evidence |
|--------|---------------|----------|
| Inspect existing frontend patterns | `READ` | Components, routes, hooks, styles |
| Select component and state approach | `SELECT` | Server/client and shadcn workflow |
| Implement UI code | `WRITE` | TSX, CSS, hooks, wrappers |
| Validate form/data contracts | `VALIDATE` | Zod/forms/API schemas |
| Call shadcn or verification tools | `CALL_TOOL` | Registry, lint, typecheck, tests |
| Compare responsive states | `COMPARE` | Desktop/mobile behavior |
| Report result | `NOTIFY` | Final summary |
### Tools and instruments
- React, Next.js, TypeScript, TailwindCSS v4, shadcn/ui
- `ahooks`, `es-toolkit`, `nuqs`, TanStack Query, Jotai, TanStack React Form, `zod`
- Lint, typecheck, tests, and browser inspection when applicable
### Canonical workflow path
```bash
rg --files
rg "components/ui|shadcn|use client|generateMetadata|useQuery|i18n|design-tokens" .
```
Then run the project's frontend verification commands, typically lint, typecheck, tests, and browser/responsive checks when the UI changes.
### Resource scope
| Scope | Resource target |
|-------|-----------------|
| `CODEBASE` | Frontend routes, components, styles, hooks, tests |
| `LOCAL_FS` | Design tokens, i18n files, resource references |
| `PROCESS` | Build, lint, typecheck, test, browser commands |
| `NETWORK` | Backend APIs or registry tools when required |
### Preconditions
- Target UI behavior and affected frontend area are identifiable.
- Required design tokens, i18n, and API contracts are available or assumptions are stated.
### Effects and side effects
- Mutates frontend source, styles, tests, and possibly i18n keys.
- May add dependencies or shadcn components only when justified by project conventions.
- Does not edit `components/ui/*` directly.
### Guardrails
1. Follow the existing React, Next.js, TypeScript, and FSD-lite architecture in the target project.
2. Use `shadcn/ui` primitives and wrappers for UI work; treat `components/ui/*` as read-only.
3. Keep server/client boundaries explicit: Server Components for static/layout work, Client Components for interaction and hooks.
4. Use project sources of truth for design tokens, i18n strings, and shared utilities before adding local alternatives.
5. Run the execution checklist before handoff and include relevant verification results.
6. **Next.js 16 `proxy.ts` is mandatory; `middleware.ts` is BANNED**: this project is Next.js 16+. `middleware.ts` is NOT "deprecated" — it is forbidden, touch it and you die. The canonical request-proxy / auth-gate file is `proxy.ts` (root or `src/`) exporting a `proxy` function. NEVER create, recommend, suggest, or "restore" `middleware.ts`. NEVER flag `proxy.ts` as dead code, unused, or not-wired. Any such finding is a fatal self-error — retract it immediately and write `proxy.ts`.
### Libraries
| Category | Library |
|----------|---------|
| Framework | `next@16+` (App Router) + `react@19+` — `next < 16` is BANNED |
| Date | `luxon` |
| Styling | `TailwindCSS v4` + `shadcn/ui` |
| Hooks | `ahooks` (pre-made hooks preferred) |
| Utils | `es-toolkit` (first choice) |
| State (URL) | `nuqs` |
| State (Server) | `TanStack Query` |
| State (Client) | `Jotai` (minimize use) |
| Forms | `@tanstack/react-form` + `zod` |
| Auth | `better-auth` (client SDK only — never import server library or database adapters) |
| Animation | `motion` — import from `motion/react`. `framer-motion` (legacy package name) is BANNED. |
### Shadcn Workflow
1. Search: `shadcn_search_items_in_registries`
2. Review: `shadcn_get_item_examples_from_registries`
3. Install: `shadcn_get_add_command_for_items`
### Server vs Client Components
- **Server Components**: Layouts, marketing pages, SEO metadata (`generateMetadata`, `sitemap`)
- **Client Components**: Interactive features and `useQuery` hooks
### UI Implementation (Shadcn/UI)
- **Usage**: Prefer strict shadcn primitives (`Card`, `Sheet`, `Typography`, `Table`) over `div` or generic classes.
- **Responsiveness**: Use `Drawer` (mobile) vs `Dialog` (desktop) via `useResponsive`.
- **Customization**: Treat `components/ui/*` as read-only. Create wrappers (e.g., `components/common/ProductButton.tsx`) or use `cva` composition. Never edit `components/ui/button.tsx` directly.
### Sources of Truth
- **DESIGN.md** (project root): visual system source of truth — read Section 9 (Agent Prompt Guide) verbatim for component prompts when present
- **Design Tokens**: `packages/design-tokens` (OKLCH) — never hardcode colors
- **i18n strings**: `packages/i18n` — never hardcode UI text
- **Custom utilities**: check `es-toolkit` first; if implementing custom logic, >90% unit test coverage is mandatory
### Designer Collaboration
- **Sync**: Map code variables to Figma layer names
- **UX**: Ensure key actions are visible "Above the Fold"
## References
1. Follow `resources/execution-protocol.md` step by step.
2. See `resources/examples.md` for input/output examples.
3. Before submitting, run `resources/checklist.md`.
Vendor-specific execution protocols are injected automatically by `oma agent:spawn`.
Source files live under `../_shared/runtime/execution-protocols/{vendor}.md`.
- Project frontend rules (MUST load before review/implementation): `../../rules/frontend.md`
- Tech stack & Serena shortcuts: `resources/tech-stack.md`
- Execution steps: `resources/execution-protocol.md`
- Code examples: `resources/examples.md`
- Code snippets: `resources/snippets.md`
- Checklist: `resources/checklist.md`
- Error recovery: `resources/error-playbook.md`
- Component template: `resources/component-template.tsx`
- Tailwind rules: `resources/tailwind-rules.md`
- Context loading: `../_shared/core/context-loading.md`
- Reasoning templates: `../_shared/core/reasoning-templates.md`
- Clarification: `../_shared/core/clarification-protocol.md`
- Context budget: `../_shared/core/context-budget.md`
- Lessons learned: `../_shared/core/lessons-learned.md`
> [!IMPORTANT]
> Treat `components/ui/*` as read-only. Create wrappers for customization.
© First Fluke · MIT · first-fluke/oh-my-agent
Similar skills
All skills for Frontend and UI →oma-frontend by other authors comes first.