ai-developer-skill-os 1.0.0

package/skills/engineering/refactor/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: refactor
+description: >-
+  Tái cấu trúc và dọn dẹp mã nguồn để dễ bảo trì hơn mà không làm thay đổi logic hoạt động bên ngoài.
+version: 1.0.0
+category: engineering
+tags: [refactor, clean-code, restructure, technical-debt, maintainability]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Refactor — Safe Restructuring
+
+> **Language rule:**
+> Use **English** for: code, identifiers, pattern names, file paths, technical terms.
+> Use **the user's language** for: explanations, questions, and summaries.
+
+> ⚠️ **Core constraint: Refactoring must NOT change observable behavior.**
+> If behavior changes are needed → that is a feature, not a refactor.
+> Stop and clarify with the user before proceeding.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User says "clean up", "refactor", "it's too messy", "hard to maintain"
+- Code has grown beyond its original design (God component, fat service, spaghetti logic)
+- Duplicate patterns exist across multiple files
+- `project-audit` identified architecture issues (P2/P3) ready to be addressed
+- User asks to "improve code quality" without changing functionality
+
+**Not this skill** → Use `bug-fix` if behavior is wrong. Use `migration` if upgrading dependencies.
+
+---
+
+## Scope
+
+- ✅ Rename for clarity (variables, functions, files, components)
+- ✅ Extract reusable logic into functions, hooks, services, or utilities
+- ✅ Remove dead code, unused imports, and orphaned files
+- ✅ Split large components / functions into focused units
+- ✅ Apply consistent patterns across the codebase
+- ✅ Improve type coverage (replace `any`, add missing types)
+- ✅ Reduce complexity (flatten nested conditions, simplify logic)
+
+---
+
+## Non-goals
+
+- ❌ Do NOT change behavior — if you must, stop and discuss first
+- ❌ Do NOT change public APIs or exported interfaces without explicit approval
+- ❌ Do NOT rewrite everything — prefer incremental, targeted changes
+- ❌ Do NOT apply opinionated style changes (formatting belongs to linter/prettier)
+- ❌ Do NOT introduce new dependencies
+- ❌ Do NOT refactor code unrelated to the stated scope
+
+---
+
+## Severity Levels (for issues found during analysis)
+
+| Level | Meaning |
+|-------|---------|
+| P0 | Refactor introduces breaking change — stop immediately |
+| P1 | High coupling or duplication blocking feature work |
+| P2 | Code smell reducing maintainability |
+| P3 | Minor naming or style inconsistency |
+
+---
+
+## Workflow
+
+### Phase 1 — Understand Current State
+
+Before changing anything:
+1. Read the target code thoroughly
+2. Identify what it does (behavior, inputs, outputs, side effects)
+3. Note all callers and dependents of the code being refactored
+4. Check for existing tests — these are the safety net
+
+If there are **no tests** for the code being refactored → recommend writing characterization tests first, or proceed with extra caution and document risks.
+
+---
+
+### Phase 2 — Identify Refactor Targets
+
+Common code smells to look for:
+
+| Smell | Description |
+|-------|-------------|
+| God Component/Function | Does too many things — split by responsibility |
+| Duplicate Logic | Same pattern repeated — extract to shared utility |
+| Long Parameter Lists | >4 params — use options object |
+| Deep Nesting | >3 levels of if/else — flatten with early returns |
+| Magic Numbers/Strings | Unnamed constants — extract to named constants |
+| Dead Code | Unused variables, functions, imports — remove |
+| Inconsistent Naming | Mixed conventions — standardize |
+| Missing Types | `any`, missing return types — add precise types |
+| Large Files | >300 lines — consider splitting by concern |
+
+---
+
+### Phase 3 — Plan the Refactor
+
+Create a step-by-step plan before touching code:
+
+1. List each specific change with its justification
+2. Order changes from lowest to highest risk
+3. Identify what tests must pass after each step
+4. Flag any changes that touch shared/exported code
+
+Present plan to user if scope is large or changes are risky.
+
+---
+
+### Phase 4 — Execute Incrementally
+
+Apply changes in small, verifiable steps:
+
+**Safe refactor order:**
+1. Rename (lowest risk — IDEs can do this safely)
+2. Extract (pull logic into new functions/hooks without changing callers)
+3. Inline (remove unnecessary abstraction)
+4. Move (relocate to correct file/folder)
+5. Simplify (reduce complexity in logic)
+6. Remove (delete dead code last — confirm nothing breaks)
+
+After **each step** → verify tests still pass before moving on.
+
+---
+
+### Phase 5 — Verify Behavior Preserved
+
+- [ ] All existing tests pass
+- [ ] Run lint and type-check — clean
+- [ ] Manual smoke test of affected functionality
+- [ ] No new `any` types introduced
+- [ ] No unused imports or dead code left
+- [ ] Public API unchanged (or explicitly approved to change)
+
+---
+
+### Phase 6 — Report
+
+Document what changed and why:
+
+```
+What changed:   [List of changes]
+Why:            [Specific smell or issue addressed]
+Risk level:     [Low / Medium / High]
+Tests status:   [All pass / N new tests added]
+Behavior:       [Unchanged — verified]
+```
+
+---
+
+## Decision Tree
+
+```
+Is there existing test coverage?
+  ├── Yes → Proceed — tests are the safety net
+  └── No  → Recommend characterization tests first
+              ├── User agrees → write tests then refactor
+              └── User wants to proceed anyway → proceed with caution, document risk
+
+Does the refactor change public APIs?
+  ├── Yes → Stop — confirm with user, this may be a breaking change
+  └── No  → Proceed
+
+Is the scope larger than expected?
+  ├── Yes → Present updated plan, get approval before continuing
+  └── No  → Continue
+```
+
+---
+
+## Output Format
+
+```
+🔧 Refactor Summary
+─────────────────────────────────────────────────
+Scope:        [What was refactored]
+Changes:      [N files modified, N extracted, N removed]
+
+Changes applied:
+  ✅ [Rename: oldName → newName in path/to/file.ts]
+  ✅ [Extract: logic → useCustomHook in path/to/hook.ts]
+  ✅ [Remove: dead code in path/to/old.ts]
+  ✅ [Split: LargeComponent → ComponentA + ComponentB]
+
+📊 Quality improvement:
+  Before: [brief description of the problem]
+  After:  [brief description of improvement]
+
+✅ Verification:
+  Tests:     PASS (N tests)
+  Lint:      Clean
+  Types:     No new `any`
+  Behavior:  Unchanged
+
+⚠️  Notes:
+  [Any assumptions, risks, or follow-up suggestions]
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Behavior is unchanged — verified with tests or manual check
+- [ ] All tests pass
+- [ ] Lint and type-check clean
+- [ ] No dead code, unused imports, or console.logs left
+- [ ] Public APIs unchanged (or explicitly approved)
+- [ ] Changes are documented with justification
+- [ ] No new dependencies introduced
+
+---
+
+## Examples
+
+See `examples/` folder.

package/skills/frontend/accessibility-audit/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: accessibility-audit
+description: >-
+  Kiểm tra và sửa lỗi khả năng tiếp cận (a11y/WCAG). Đảm bảo hỗ trợ phím, screen reader và semantic HTML.
+version: 1.0.0
+category: frontend
+tags: [accessibility, a11y, aria, wcag, screen-reader, keyboard]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Accessibility (A11y) Audit
+
+> **Language rule:**
+> Use **English** for: ARIA attributes, HTML tags, WCAG guidelines, technical terms.
+> Use **the user's language** for: explanations, summaries, and questions.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User asks to "make this accessible", "fix a11y", or "audit accessibility"
+- Building complex interactive components (modals, dropdowns, tabs, sliders)
+- Preparing an app for production or public release
+- Project audit flags missing semantic HTML or ARIA issues
+
+---
+
+## Scope
+
+- ✅ **Keyboard Navigation:** Ensure all interactive elements are reachable via `Tab`, and operable via `Enter`/`Space`/Arrows. Focus management (trapping focus in modals).
+- ✅ **Screen Reader Support:** Add proper `aria-` attributes, `alt` text, and visually hidden text (`sr-only`).
+- ✅ **Semantic HTML:** Replace `div` soups with `<nav>`, `<main>`, `<article>`, `<button>`, etc.
+- ✅ **Color Contrast:** Verify text vs. background contrast meets WCAG AA (4.5:1 for normal text).
+- ✅ **Form Labels:** Ensure all inputs have associated `<label>`s or `aria-label`s.
+
+---
+
+## Non-goals
+
+- ❌ Do NOT completely redesign the UI visually (unless fixing a severe contrast issue, and even then, ask first).
+- ❌ Do NOT overuse ARIA. The first rule of ARIA is: "No ARIA is better than bad ARIA." Use semantic HTML first.
+
+---
+
+## Workflow
+
+### Phase 1 — Semantic HTML Check
+
+Scan the component for basic HTML semantics:
+- Are buttons actually `<button>` elements (not `<div onClick>`)?
+- Are links actually `<a>` elements with `href`s?
+- Do images have meaningful `alt` text (or `alt=""` if decorative)?
+- Are headings (`h1`-`h6`) in a logical, unbroken hierarchy?
+
+### Phase 2 — Keyboard & Focus Management
+
+- Can the user tab through the component logically?
+- Does every interactive element have a visible focus state (`:focus-visible`)?
+- For Modals/Dialogs: Is focus trapped inside when open? Is focus restored when closed?
+- For custom widgets (Tabs/Dropdowns): Implement correct arrow key navigation per WAI-ARIA authoring practices.
+
+### Phase 3 — Screen Reader (ARIA) Check
+
+- Do custom interactive elements have correct `role`s (e.g., `role="tablist"`)?
+- Is dynamic state communicated? (`aria-expanded`, `aria-selected`, `aria-invalid`, `aria-busy`).
+- Are icon-only buttons properly labeled? (`aria-label` or `<span className="sr-only">Label</span>`).
+- Are dynamic live regions used for important announcements (`aria-live="polite"` or `assertive`)?
+
+### Phase 4 — Contrast & Visuals
+
+- Check text colors against backgrounds.
+- Ensure form fields have visible borders or indicators.
+- Ensure information is not conveyed *only* by color (e.g., a red border for an error must also have error text).
+
+---
+
+## Decision Tree
+
+```
+Is the component a native HTML element (e.g., standard `<button>`)?
+  ├── Yes → Ensure it has accessible text/labels. No ARIA roles needed.
+  └── No  → (e.g., a custom `div` acting as a checkbox)
+              ├── Can it be refactored to use native HTML?
+              │     ├── Yes → Refactor to native HTML `<input type="checkbox">`
+              │     └── No  → Apply `role="checkbox"`, `tabIndex={0}`, `aria-checked`, and keyboard event handlers.
+```
+
+---
+
+## Output Format
+
+```
+♿ Accessibility Audit Report
+─────────────────────────────────────────────────
+Component:  [ComponentName]
+
+Issues Found & Fixed:
+  ✅ Semantic HTML: Replaced `<div onClick>` with `<button>`
+  ✅ Screen Readers: Added `aria-label` to icon-only close button
+  ✅ Keyboard: Added focus trap inside the Modal
+  ✅ Forms: Associated `<label htmlFor="email">` with Input
+
+⚠️ Remaining Warnings (Manual Check Required):
+  - Please verify color contrast of primary button in light mode (needs 4.5:1 ratio).
+
+🔗 Next Steps:
+  Code updated. Recommend testing with a screen reader (VoiceOver/NVDA).
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Semantic HTML preferred over ARIA
+- [ ] Keyboard navigation (Tab + Enter/Space) works correctly
+- [ ] Focus is visible on all interactive elements
+- [ ] Forms have proper labels
+- [ ] Icon-only buttons have accessible names

package/skills/frontend/component-generator/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: component-generator
+description: >-
+  Tạo các UI Component độc lập, tái sử dụng được, có type an toàn và tuân thủ chuẩn design system.
+version: 1.0.0
+category: frontend
+tags: [component, react, vue, ui, props, reusable]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Component Generator
+
+> **Language rule:**
+> Use **English** for: code, component names, prop types, technical terminology.
+> Use **the user's language** for: explanations, summaries, and questions.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User says "create a Card component", "make a reusable Button", "extract this into a component"
+- A larger skill (`ui-builder`, `form-builder`) requires a new isolated UI piece to be built
+- Refactoring a large component by splitting it into smaller, reusable parts
+
+---
+
+## Scope
+
+- ✅ Generate a single, focused component (e.g., `UserCard`, `StatBadge`, `Dropdown`)
+- ✅ Define strict, explicit types/interfaces for all props
+- ✅ Implement component variants (e.g., `size`, `color`, `variant`) if needed
+- ✅ Follow project styling rules (Tailwind, CSS Modules, Styled Components)
+- ✅ Ensure accessibility (ARIA attributes, semantic HTML) where applicable
+
+---
+
+## Non-goals
+
+- ❌ Do NOT build full pages or complex screens (delegate to `ui-builder`)
+- ❌ Do NOT handle complex business logic or data fetching inside a dumb/presentational component
+- ❌ Do NOT overwrite existing components without explicit instruction
+
+---
+
+## Workflow
+
+### Phase 1 — Component Design
+
+Determine:
+1. **Name:** PascalCase (e.g., `ProductCard`).
+2. **Responsibility:** What exactly does this component do? Keep it single-responsibility.
+3. **Props:** What data does it need from its parent? What events does it emit?
+
+---
+
+### Phase 2 — API (Props) Definition
+
+Draft the interface first.
+- Make required props explicit.
+- Use optional props (`?`) for variants or non-essential data.
+- Avoid `any`.
+
+*Example:*
+```typescript
+interface ProductCardProps {
+  id: string;
+  title: string;
+  price: number;
+  imageUrl?: string;
+  isAvailable?: boolean;
+  onAddToCart: (id: string) => void;
+}
+```
+
+---
+
+### Phase 3 — Implementation
+
+Write the component code.
+1. Use destructuring for props.
+2. Apply styling based on `design-system` rules.
+3. Handle empty/null states (e.g., if `imageUrl` is missing, show a placeholder).
+4. Add basic interactivity (e.g., calling `onAddToCart` when clicked).
+
+---
+
+### Phase 4 — Validation
+
+- [ ] Are all props typed correctly?
+- [ ] Is it truly reusable (no hardcoded data)?
+- [ ] Does it use project design tokens?
+- [ ] Is it exported correctly according to project conventions (default vs. named export)?
+
+---
+
+## Decision Tree
+
+```
+Does the component need to manage its own state (e.g., an accordion opening/closing)?
+  ├── Yes → Add local state (`useState`). Keep it minimal.
+  └── No  → Make it a pure "dumb" component receiving props.
+
+Are there multiple visual styles requested (e.g., primary, secondary, outline)?
+  ├── Yes → Add a `variant` prop and map it to style classes.
+  └── No  → Implement the single required style.
+```
+
+---
+
+## Output Format
+
+```
+🧩 Component Generated
+─────────────────────────────────────────────────
+Name:     [ComponentName]
+Path:     [path/to/Component.tsx]
+
+Props Interface:
+  [List key props here briefly]
+
+Features:
+  • [Feature 1, e.g., "Supports primary/secondary variants"]
+  • [Feature 2, e.g., "Fully typed with TypeScript"]
+
+🔗 Next Steps:
+  Component is ready to be imported into your layout.
+```
+
+---
+
+## Examples
+
+See `examples/` folder.

package/skills/frontend/design-system/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: design-system
+description: >-
+  Ép buộc sử dụng design system, component library và token hiện có, ngăn chặn việc viết HTML/CSS rác.
+version: 1.0.0
+category: frontend
+tags: [design-system, ui-components, styling, tailwind, material-ui, shadcn]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Design System Enforcer
+
+> **Language rule:**
+> Use **English** for: component names, CSS classes, design tokens, technical terms.
+> Use **the user's language** for: explanations, summaries, and questions.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- About to build UI screens or components
+- Styling or layout work is required
+- User asks to "make it look good" or "match the design"
+- Integrating a third-party UI library (Tailwind, MUI, AntD, Shadcn)
+
+---
+
+## Scope
+
+- ✅ Identify the UI library or design system in use
+- ✅ Map standard HTML elements to project-specific components (e.g., `<button>` → `<Button>`)
+- ✅ Enforce usage of design tokens (colors, spacing, typography) instead of hardcoded values
+- ✅ Provide available component variants and props to downstream skills (`ui-builder`)
+- ✅ Prevent generation of raw CSS/inline styles if utility classes or styled-components are standard
+
+---
+
+## Non-goals
+
+- ❌ Do NOT create new base components if an equivalent already exists
+- ❌ Do NOT introduce a new styling method (e.g., don't add Tailwind if project uses CSS Modules)
+- ❌ Do NOT design full pages (delegate to `ui-builder`)
+
+---
+
+## Workflow
+
+### Phase 1 — Detect Design System
+
+Analyze dependencies and project files to identify:
+1. **Component Library:** Shadcn UI, MUI, Ant Design, Chakra, Bootstrap, custom internal library?
+2. **Styling Method:** Tailwind CSS, CSS Modules, Styled Components, Emotion, SCSS, Vanilla CSS?
+3. **Location of Shared Components:** Usually `src/components/ui/`, `src/shared/components/`, or from an npm package.
+4. **Design Tokens:** `tailwind.config.js`, `theme.ts`, `variables.scss`.
+
+---
+
+### Phase 2 — Component Mapping
+
+Before `ui-builder` generates code, create a mapping table for required elements:
+
+| Standard Element | Project Component | Source / Import Path |
+|------------------|-------------------|----------------------|
+| `<button>` | `<Button>` | `@/components/ui/button` |
+| `<input type="text">` | `<Input>` | `@/components/ui/input` |
+| `<div>` (Card) | `<Card>` | `@/components/ui/card` |
+| `<h1>` | `<Typography variant="h1">` | `@mui/material` |
+
+---
+
+### Phase 3 — Token Extraction
+
+Identify available tokens for spacing, colors, and typography to avoid hardcoding:
+- *Instead of:* `margin-top: 16px; color: #3b82f6;`
+- *Use:* `mt-4 text-blue-500` (Tailwind) or `theme.spacing(2)` (MUI) or `var(--primary-color)`.
+
+---
+
+### Phase 4 — Rule Enforcement
+
+Pass strict instructions to `ui-builder` or `component-generator`:
+- "You MUST use `<Button>` instead of `<button>`."
+- "You MUST use Tailwind classes for all styling. No inline `style={{}}` allowed."
+
+---
+
+## Decision Tree
+
+```
+Does the project use a component library (e.g., Shadcn, MUI)?
+  ├── Yes → Is the required component available?
+  │           ├── Yes → Require its use
+  │           └── No  → Instruct `component-generator` to create it following library style
+  └── No  → Check if custom shared components exist
+              ├── Yes → Map to custom shared components
+              └── No  → Use raw HTML but enforce project's styling method (e.g., Tailwind)
+
+Does the project use utility classes (Tailwind)?
+  ├── Yes → Forbid inline styles or custom CSS files
+  └── No  → Enforce existing CSS Modules / Styled Components patterns
+```
+
+---
+
+## Output Format
+
+```
+🎨 Design System Rules
+─────────────────────────────────────────────────
+Library:        [Shadcn / MUI / Tailwind / Custom / etc.]
+Styling Method: [Tailwind / CSS Modules / Styled Components]
+
+Component Mapping for this task:
+  ✅ Button  → `<Button>` from `@/components/ui/button`
+  ✅ Input   → `<Input>` from `@/components/ui/input`
+  ✅ Layout  → Flexbox with Tailwind (`flex flex-col gap-4`)
+
+Styling Rules Enforced:
+  • No raw HTML `<button>` allowed
+  • No inline styles allowed
+  • Use primary color token for CTAs
+
+🔗 Next Steps:
+  Passing these rules to `ui-builder` to generate the UI.
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Design system and styling method correctly identified
+- [ ] Mappings created for all necessary UI elements
+- [ ] Design tokens (spacing/colors) prioritized over hardcoded values
+- [ ] Strict enforcement rules passed to next skill