ai-developer-skill-os 1.0.0

package/skills/frontend/form-builder/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: form-builder
+description: >-
+  Xây dựng Form chuẩn xác với quản lý trạng thái, validate dữ liệu (Zod, Yup) và xử lý hiển thị lỗi.
+version: 1.0.0
+category: frontend
+tags: [form, validation, react-hook-form, zod, yup, formik]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Form Builder
+
+> **Language rule:**
+> Use **English** for: field names, validation rules, code, technical concepts.
+> Use **the user's language** for: explanations, error message text (unless specified otherwise), and summaries.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User says "create a login form", "add a settings page", "build a contact form"
+- User provides a data model and needs a UI to create/edit it
+- A form needs complex validation logic added
+- Refactoring a messy form into a structured library pattern (e.g., React Hook Form)
+
+---
+
+## Scope
+
+- ✅ Define the form data schema and validation rules
+- ✅ Manage form state efficiently (preventing unnecessary re-renders)
+- ✅ Map form fields to the project's design system components
+- ✅ Handle submission state (loading, success, error)
+- ✅ Handle validation errors and display them accessibly
+- ✅ Integrate with `api-integration` for submission
+
+---
+
+## Non-goals
+
+- ❌ Do NOT reinvent form state management if a library is present
+- ❌ Do NOT use raw HTML inputs if design system components exist
+- ❌ Do NOT skip validation (client-side validation is required)
+
+---
+
+## Workflow
+
+### Phase 1 — Schema Design
+
+Define the exact shape of the data the form collects.
+Determine validation rules for each field (required, min length, email format, etc.).
+
+If the project uses Zod, Yup, or Joi, define the schema first.
+*Example:*
+```typescript
+const userFormSchema = z.object({
+  email: z.string().email("Invalid email address"),
+  password: z.string().min(8, "Password must be at least 8 characters"),
+});
+```
+
+---
+
+### Phase 2 — State Management Selection
+
+Check project dependencies for form libraries:
+1. `react-hook-form` (Preferred for React)
+2. `formik`
+3. Custom Vue/Svelte bindings
+4. Standard controlled components (`useState`) if no library exists and form is simple.
+
+---
+
+### Phase 3 — Component Assembly
+
+1. Set up the form wrapper and submission handler.
+2. For each field in the schema, render the appropriate UI component (from `design-system`).
+3. Connect the UI component to the form state (register / Controller).
+4. Render error messages below fields if validation fails.
+
+---
+
+### Phase 4 — Submission & Integration
+
+- Add `isLoading` state to the submit button.
+- Disable submit button during submission.
+- On success: Show success message or redirect, and optionally reset form.
+- On error: Display backend error messages (toast or form-level alert).
+
+---
+
+## Decision Tree
+
+```
+Does the project use a validation library (Zod, Yup)?
+  ├── Yes → Use it to define schema and pass to form resolver
+  └── No  → Implement standard HTML5 validation or simple manual validation logic
+
+Is it a complex multi-step form (wizard)?
+  ├── Yes → Break into sub-components, use global or lifted state for form data
+  └── No  → Handle state locally within the single form component
+```
+
+---
+
+## Output Format
+
+```
+📝 Form Built
+─────────────────────────────────────────────────
+Name:     [FormName]
+Schema:   [Zod / Yup / Manual]
+Library:  [React Hook Form / Formik / Native]
+
+Fields Implemented:
+  ✅ email (string, required, email)
+  ✅ password (string, required, min: 8)
+
+Integration:
+  - Validation: Client-side wired up
+  - Submission: Wired to `[submitFunction]`
+  - Loading UI: Handled on submit button
+
+🔗 Next Steps:
+  Make sure the API endpoint is ready to accept this payload.
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Form uses existing design system components (Inputs, Buttons)
+- [ ] Client-side validation is implemented
+- [ ] Error messages are displayed properly
+- [ ] Loading state disables the submit button
+- [ ] Accessibility: Inputs have associated labels and error ARIA attributes

package/skills/frontend/frontend-architecture/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: frontend-architecture
+description: >-
+  Phân tích cấu trúc thư mục frontend và quyết định vị trí đặt file chuẩn xác theo kiến trúc hiện tại.
+version: 1.0.0
+category: frontend
+tags: [architecture, folder-structure, conventions, file-placement]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Frontend Architecture
+
+> **Language rule:**
+> Use **English** for: code, folder names, architecture terms, technical rules.
+> Use **the user's language** for: explanations, questions, and summaries.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- About to create new files or components
+- User asks "where should I put this file?" or "how should I organize this?"
+- Moving or refactoring code across different modules
+- Inheriting an unfamiliar frontend project
+
+---
+
+## Scope
+
+- ✅ Discover the existing frontend folder structure
+- ✅ Define where new components, hooks, services, and types should be placed
+- ✅ Enforce separation of concerns (e.g., UI vs. Business Logic vs. Data)
+- ✅ Identify architectural patterns in use (e.g., Feature-based, Layer-based)
+- ✅ Validate file placement before execution by other skills
+
+---
+
+## Non-goals
+
+- ❌ Do NOT rewrite the entire project architecture unless explicitly asked
+- ❌ Do NOT generate code (delegate to `component-generator` or `ui-builder`)
+- ❌ Do NOT enforce personal preferences over established project conventions
+
+---
+
+## Severity Levels
+
+| Level | Meaning |
+|-------|---------|
+| P0 | Architectural violation that breaks the build or creates circular dependencies |
+| P1 | File placed in completely wrong layer (e.g., API logic in UI component) |
+| P2 | Inconsistent folder or file naming |
+| P3 | Minor deviation from convention |
+
+---
+
+## Workflow
+
+### Phase 1 — Structure Discovery
+
+*(Relies on `context-manager` if already loaded)*
+
+Analyze the root source directory (e.g., `src/`, `app/`):
+1. **Layer-based:** `components/`, `hooks/`, `services/`, `utils/`, `types/`
+2. **Feature-based:** `features/auth/`, `features/products/`
+3. **Framework-specific:** `app/` (Next.js App Router), `pages/` (Next.js Pages Router, Nuxt)
+4. **Domain-driven:** `domains/user/`, `domains/payment/`
+5. **FSD (Feature Sliced Design):** `app/`, `processes/`, `pages/`, `widgets/`, `features/`, `entities/`, `shared/`
+
+---
+
+### Phase 2 — Rule Extraction
+
+Based on discovery, define the project's rules for:
+- **Components:** Are they flat? Grouped by feature? Atomic design?
+- **Hooks:** Shared in `src/hooks/` or collocated with components?
+- **State:** Global store vs. feature stores?
+- **API/Services:** Where are HTTP calls made?
+- **Types:** Centralized `types/` or collocated?
+- **Naming Conventions:** PascalCase, camelCase, kebab-case, `index.ts` usage?
+
+---
+
+### Phase 3 — File Placement Decision
+
+When a new feature/component is requested, map it to the structure:
+
+**Input:** "Create a User Profile card that fetches user data."
+**Decision:**
+- UI Component: `src/features/user/components/UserProfileCard.tsx`
+- API Hook: `src/features/user/api/useUser.ts`
+- Types: `src/features/user/types/index.ts`
+
+---
+
+### Phase 4 — Enforcement & Validation
+
+Before passing control to a generation skill (like `ui-builder`), ensure the plan adheres to the rules.
+
+- [ ] Does it mix concerns? (e.g., putting an API call directly in a shared UI button)
+- [ ] Does it violate import boundaries? (e.g., a shared component importing from a specific feature)
+- [ ] Is the naming consistent?
+
+---
+
+## Decision Tree
+
+```
+Is the project using a Feature-based structure?
+  ├── Yes → Place feature-specific code in `features/<feature-name>/`
+  └── No  → Use Layer-based structure (`components/`, `hooks/`, etc.)
+
+Is the code shared across multiple domains/features?
+  ├── Yes → Place in `shared/` or global `components/` / `hooks/`
+  └── No  → Collocate with the specific domain/feature
+
+Are there existing examples of this type of file?
+  ├── Yes → Copy their placement and naming pattern
+  └── No  → Propose a standard location and ask user to confirm
+```
+
+---
+
+## Output Format
+
+```
+🏗️ Frontend Architecture Plan
+─────────────────────────────────────────────────
+Structure Type: [Feature-based / Layer-based / FSD / etc.]
+Naming:         [PascalCase for components, camelCase for functions]
+
+File Placement:
+  📄 [path/to/new/file1.tsx] — [Why it goes here]
+  📄 [path/to/new/file2.ts]  — [Why it goes here]
+
+⚠️ Constraints enforced:
+  • [Constraint 1, e.g., "API calls must be in hooks, not components"]
+  • [Constraint 2, e.g., "Shared UI components cannot import from features/"]
+
+🔗 Next Steps:
+  Delegating to `[skill-name]` to generate the files.
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Structure type identified correctly
+- [ ] File placement follows existing conventions
+- [ ] Naming matches project standards
+- [ ] Separation of concerns maintained
+- [ ] Plan ready to be executed by generation skills

package/skills/frontend/frontend-debug/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: frontend-debug
+description: >-
+  Chẩn đoán và sửa các lỗi đặc thù frontend như Hydration error, infinite re-render, stale closure và vỡ CSS.
+version: 1.0.0
+category: frontend
+tags: [debug, react, hydration, rerender, css, state-bug]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Frontend Debugger
+
+> **Language rule:**
+> Use **English** for: code, error messages, stack traces, technical patterns.
+> Use **the user's language** for: explanations, root cause summaries, and questions.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User reports a UI-specific bug ("screen is blank", "button doesn't work")
+- React throws a Hydration Error (`Text content did not match. Server: "A" Client: "B"`)
+- React throws an infinite loop error (`Too many re-renders`)
+- CSS styling is broken or overflowing unexpectedly
+- Form validation behaves incorrectly
+
+**Note:** For backend or general logic bugs, use `bug-fix`. For performance issues, use `frontend-performance`.
+
+---
+
+## Scope
+
+- ✅ Diagnose and fix React hydration mismatches (Next.js / SSR)
+- ✅ Fix infinite loops in `useEffect` and missing dependencies
+- ✅ Resolve state staleness (stale closures in async functions or hooks)
+- ✅ Fix CSS layout issues (Flexbox/Grid blowouts, z-index stacking context)
+- ✅ Provide a targeted, minimal fix that doesn't break other UI elements
+
+---
+
+## Non-goals
+
+- ❌ Do NOT rewrite the entire component to fix a small CSS bug
+- ❌ Do NOT disable hydration checks (`suppressHydrationWarning`) unless absolutely necessary and justified
+- ❌ Do NOT apply quick-fixes (like `// @ts-ignore` or wrapping everything in `setTimeout`) without understanding the root cause
+
+---
+
+## Workflow
+
+### Phase 1 — Reproduction & Isolation
+
+1. Identify the exact error message or visual symptom.
+2. Isolate the component causing the issue.
+3. Determine the environment (SSR, CSR, mobile, specific browser).
+
+---
+
+### Phase 2 — Common Issue Diagnosis
+
+**Hydration Errors (Next.js/SSR):**
+- Cause: Rendering `window`, `localStorage`, or random data (e.g., `Math.random()`, Dates) on the first pass.
+- Fix: Move client-only rendering inside a `useEffect` (isMounted pattern) or use dynamic imports with `ssr: false`.
+
+**Too many re-renders:**
+- Cause: Updating state directly in the render body, or inside a `useEffect` without proper dependencies.
+- Fix: Move state updates into event handlers, or fix `useEffect` dependencies.
+
+**Stale Closures:**
+- Cause: A `useEffect` or `useCallback` is using old state because it's missing from the dependency array.
+- Fix: Add dependencies, use refs (`useRef`) for mutable values, or use functional state updates (`setState(prev => prev + 1)`).
+
+**CSS Z-Index/Stacking Issues:**
+- Cause: Missing `position: relative/absolute` on parent, or a new stacking context was created.
+- Fix: Inspect parent elements, adjust `z-index`, or use Portals for modals.
+
+---
+
+### Phase 3 — Fix Application
+
+Apply the minimal fix required to resolve the issue while preserving surrounding logic and styles.
+
+---
+
+## Decision Tree
+
+```
+Is it a Hydration Error?
+  ├── Yes → Is it caused by client-side APIs (window/localStorage)?
+  │           ├── Yes → Use `useEffect` to delay rendering until mounted
+  │           └── No  → Check for mismatched HTML tags (e.g., <p> inside <p>)
+  └── No  → Proceed to next check
+
+Is it an infinite loop?
+  ├── Yes → Check `useEffect` dependencies. Are objects/arrays re-created every render?
+  │           ├── Yes → Memoize them (`useMemo`) or move outside component
+  │           └── No  → Ensure `setState` isn't called unconditionally in render
+  └── No  → Proceed
+```
+
+---
+
+## Output Format
+
+```
+🪲 Frontend Debug Report
+─────────────────────────────────────────────────
+Symptom:    [Description of the bug]
+Root Cause: [Explanation of why it failed, e.g., Stale Closure in useEffect]
+
+🔧 Fix Applied:
+  [Brief description of the code change]
+
+✅ Verification:
+  - Error no longer throws
+  - UI renders correctly
+
+⚠️ Notes:
+  [Any side effects or things to watch out for]
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Root cause clearly identified (not just patched)
+- [ ] Fix is minimal and targeted
+- [ ] No Hydration warnings remain
+- [ ] Component doesn't infinitely loop
+- [ ] No regression on related UI

package/skills/frontend/frontend-performance/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: frontend-performance
+description: >-
+  Tối ưu hóa hiệu năng frontend: giảm kích thước bundle, chặn re-render thừa, lazy load và cải thiện Web Vitals.
+version: 1.0.0
+category: frontend
+tags: [performance, optimization, render, bundle-size, lazy-load, memoization]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Frontend Performance Optimizer
+
+> **Language rule:**
+> Use **English** for: code, metrics (LCP, CLS, FID), technical terms (memoization, lazy loading).
+> Use **the user's language** for: explanations, summaries, and questions.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User reports "app is slow", "loading takes too long", or "UI freezes"
+- Core Web Vitals (LCP, FID/INP, CLS) are failing
+- React DevTools shows excessive re-renders
+- `project-audit` flags a performance issue (P2)
+- Need to optimize images, bundle size, or data fetching
+
+---
+
+## Scope
+
+- ✅ **Render Optimization:** Prevent unnecessary re-renders (React `memo`, `useMemo`, `useCallback`).
+- ✅ **Bundle Optimization:** Code splitting, lazy loading components/routes (`React.lazy`, Next.js `dynamic`).
+- ✅ **Asset Optimization:** Image optimization (WebP, Next/Image, lazy loading `loading="lazy"`).
+- ✅ **Data Fetching:** Caching, prefetching, pagination, virtualization for large lists.
+- ✅ **Core Web Vitals:** Fix layout shifts (CLS), improve Largest Contentful Paint (LCP).
+
+---
+
+## Non-goals
+
+- ❌ Do NOT blindly wrap everything in `useMemo` or `React.memo` (this can degrade performance).
+- ❌ Do NOT optimize prematurely if there is no measured performance issue.
+- ❌ Do NOT rewrite business logic unless it is the direct cause of the bottleneck.
+
+---
+
+## Workflow
+
+### Phase 1 — Identify the Bottleneck
+
+Determine what kind of performance issue it is:
+1. **Network/Load Time:** Slow initial page load, large bundle size, heavy images.
+2. **Render/Runtime:** UI is sluggish, typing lags, animation stutters (too many re-renders).
+3. **Data/Memory:** App crashes or slows down over time, large lists lagging.
+
+### Phase 2 — Common Fixes by Category
+
+#### 1. Fixing Unnecessary Re-renders (React)
+- Move state down to the smallest possible component.
+- Use `React.memo` for heavy pure components that receive the same props.
+- Stable references: Use `useMemo` for expensive calculations or object props, and `useCallback` for function props passed to memoized children.
+- *Warning:* Measure first! Memoization has an upfront cost.
+
+#### 2. Fixing Bundle Size (Code Splitting)
+- Are large libraries (like `lodash`, `moment`, `echarts`) imported entirely? Use named imports or alternative libraries.
+- Lazy load routes or heavy components below the fold:
+  ```typescript
+  const HeavyChart = React.lazy(() => import('./HeavyChart'));
+  // Wrap in <Suspense fallback={<Spinner />}>
+  ```
+
+#### 3. Asset & UI Optimization
+- Add fixed `width` and `height` to images to prevent Cumulative Layout Shift (CLS).
+- Virtualize large lists (e.g., `react-window` or `@tanstack/react-virtual`) instead of rendering 1000 DOM nodes.
+- Debounce rapid events (typing in search, window resize).
+
+---
+
+### Phase 3 — Implementation
+
+Apply the targeted fix. Document why the fix improves performance.
+
+---
+
+## Decision Tree
+
+```
+Is the issue related to initial load time?
+  ├── Yes → Focus on Code Splitting (lazy loading), Image Optimization, and bundle size reduction.
+  └── No  → Is the UI lagging during interaction?
+              ├── Yes → Profile renders. Check for state updates triggering massive re-renders. Use `memo` or state colocation.
+              └── No  → Is a specific list or table slow?
+                          ├── Yes → Implement virtualization (react-window) or pagination.
+```
+
+---
+
+## Output Format
+
+```
+⚡ Performance Optimization Report
+─────────────────────────────────────────────────
+Target:      [Component / Page]
+Bottleneck:  [Brief description, e.g., "Expensive list rendering on every keystroke"]
+
+🔧 Fixes Applied:
+  ✅ Extracted Search Input state to prevent list re-rendering
+  ✅ Wrapped heavy `ChartComponent` in `React.memo`
+  ✅ Lazy-loaded below-the-fold content (`Suspense`)
+
+📈 Expected Impact:
+  - Reduced re-renders on typing from O(N) to O(1)
+  - Initial JS bundle size reduced by ~X KB
+
+⚠️ Notes:
+  Please test this on lower-end devices to confirm smooth interactions.
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Fix addresses the specific bottleneck
+- [ ] No premature memoization applied blindly
+- [ ] Layout shift (CLS) prevented (if changing images/layout)
+- [ ] Application behavior remains completely unchanged

package/skills/frontend/frontend-testing/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: frontend-testing
+description: >-
+  Viết Unit, Component và E2E test bằng Jest, Vitest, RTL, Cypress. Tập trung vào hành vi người dùng.
+version: 1.0.0
+category: frontend
+tags: [testing, jest, vitest, react-testing-library, cypress, playwright, tdd]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Frontend Testing
+
+> **Language rule:**
+> Use **English** for: code, test descriptions (`it('should...')`), mock data, technical terms.
+> Use **the user's language** for: explanations, summaries, and questions.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User asks to "write tests for this", "add unit tests", or "test this component"
+- Fixing a critical bug where a regression test is required
+- Preparing for a major release and increasing test coverage
+- Project audit flags missing tests for core business logic
+
+---
+
+## Scope
+
+- ✅ **Unit Tests:** Test pure functions, utilities, and custom hooks.
+- ✅ **Component Tests:** Test UI components using React Testing Library (RTL). Focus on user interactions and accessibility roles.
+- ✅ **Mocking:** Mock API calls (MSW, Jest mocks), modules, and timers.
+- ✅ **E2E Tests:** Write Cypress or Playwright tests for critical user flows.
+- ✅ Follow the project's existing testing framework (Jest vs Vitest).
+
+---
+
+## Non-goals
+
+- ❌ Do NOT test implementation details (e.g., checking if a specific state variable changed). Test what the user sees/does.
+- ❌ Do NOT write brittle tests (e.g., querying by CSS class names). Use ARIA roles or `data-testid`.
+- ❌ Do NOT introduce a new testing framework if one already exists.
+
+---
+
+## Workflow
+
+### Phase 1 — Environment Check
+
+Identify the testing stack:
+- Runner: Jest or Vitest?
+- DOM: React Testing Library, Vue Test Utils?
+- E2E: Cypress, Playwright?
+- Mocking: MSW (Mock Service Worker), `jest.mock`, `vi.mock`?
+
+---
+
+### Phase 2 — Strategy & Coverage
+
+Determine what needs testing:
+1. **Critical Path:** Can the user complete the primary action?
+2. **Edge Cases:** What happens on API failure? Empty state? Invalid input?
+3. **Accessibility:** Can elements be found by role?
+
+---
+
+### Phase 3 — Writing the Test (RTL Example)
+
+1. **Setup:** Render the component, wrap with necessary providers (Theme, Store, QueryClient).
+2. **Query:** Find elements using `screen.getByRole`, `screen.getByLabelText`, or `screen.getByText`.
+3. **Act:** Simulate user events using `userEvent` (preferred over `fireEvent`).
+4. **Assert:** Expect elements to be in the document, disabled, or display specific text.
+
+*Example:*
+```typescript
+it('submits the form when fields are valid', async () => {
+  const mockSubmit = vi.fn();
+  render(<LoginForm onSubmit={mockSubmit} />);
+
+  await userEvent.type(screen.getByLabelText(/email/i), 'test@example.com');
+  await userEvent.type(screen.getByLabelText(/password/i), 'password123');
+  await userEvent.click(screen.getByRole('button', { name: /login/i }));
+
+  expect(mockSubmit).toHaveBeenCalledWith({
+    email: 'test@example.com',
+    password: 'password123'
+  });
+});
+```
+
+---
+
+### Phase 4 — Mocking
+
+If the component makes API calls:
+- Prefer MSW (Mock Service Worker) for network-level mocking.
+- Fallback: Mock the API service module or custom hook.
+
+---
+
+## Decision Tree
+
+```
+Are we testing a pure function or utility?
+  ├── Yes → Write a standard Unit Test (Jest/Vitest).
+  └── No  → Are we testing a UI component?
+              ├── Yes → Use React Testing Library (focus on user behavior).
+              └── No  → Are we testing a full page flow?
+                          ├── Yes → Write an E2E test (Cypress/Playwright) or integration test.
+```
+
+---
+
+## Output Format
+
+```
+🧪 Test Suite Generated
+─────────────────────────────────────────────────
+Target:     [ComponentName or Utility]
+Type:       [Unit / Component / E2E]
+Framework:  [Vitest + RTL]
+
+Tests Added:
+  ✅ renders correctly in default state
+  ✅ displays error message on API failure
+  ✅ successfully submits user data
+
+Mocking Used:
+  - MSW handlers for `/api/users`
+  - vi.fn() for onSubmit callback
+
+🔗 Next Steps:
+  Run `npm run test` to execute the suite.
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Queries use accessible methods (`getByRole`, `getByLabelText`)
+- [ ] Events simulated with `userEvent` (if applicable)
+- [ ] External dependencies/APIs are properly mocked
+- [ ] Tests verify observable behavior, not internal state