ai-developer-skill-os 1.0.0

package/docs/HUONG_DAN_SU_DUNG.md

@@ -0,0 +1,102 @@
+# Hướng Dẫn Sử Dụng — AI Developer Skill OS
+
+**Tác giả:** Quang Khánh  
+**Phiên bản:** v1.0.0  
+
+Chào mừng bạn đến với **AI Developer Skill OS**, bộ khung quản lý kỹ năng (Skill Framework) biến các trợ lý AI (Claude Code, Kilo Code, Antigravity, Cursor, Windsurf) từ một "cỗ máy sinh code" thành một Senior Software Engineer thực thụ.
+
+---
+
+## 1. Cơ chế hoạt động (Tại sao lại cần Skin/Skill này?)
+
+Thông thường, khi bạn yêu cầu AI "Làm cho tôi tính năng X", AI sẽ nhảy ngay vào viết code. Điều này ở các dự án lớn thường dẫn đến: phá vỡ kiến trúc, tạo ra code rác, và không tuân thủ các component dùng chung.
+
+Với hệ điều hành kỹ năng (Skill OS) này:
+1. Bạn đưa ra yêu cầu.
+2. Skill **agent-orchestrator** sẽ tiếp nhận, phân tích và lên kế hoạch (Plan only).
+3. Nó gọi **context-manager** để đọc đúng những file cần thiết (chống tràn ngữ cảnh).
+4. Nó gọi các skill chuyên biệt (`ui-builder`, `api-integration`, `database-engineer`...) để thực thi từng bước.
+5. AI luôn bị ép phải dùng tiếng Anh để viết code/định nghĩa biến, nhưng sẽ dùng tiếng Việt để giao tiếp và báo cáo với bạn.
+
+---
+
+## 2. Hướng dẫn cài đặt
+
+Bộ Skin này rất linh hoạt và có thể được tích hợp vào hầu hết các AI Agent IDE hiện đại:
+
+### Cho Antigravity / Gemini IDE
+Bạn cần copy thư mục chứa các skill này vào thư mục `.agents` của dự án:
+```
+my-project/
+└── .agents/
+    └── skills/
+        ├── engineering/
+        ├── frontend/
+        └── backend/
+```
+Hoặc cấu hình Global trong máy tính của bạn tại:
+`C:\Users\<Tên-Máy-Bạn>\.gemini\config\skills\`
+
+### Cho Claude Code & Kilo Code (CLI AI Agents)
+Claude Code và Kilo Code đọc các quy tắc (rules) từ thư mục gốc của dự án.
+**Cách cài đặt:**
+1. Copy toàn bộ thư mục `rules-skill/` vào gốc dự án của bạn.
+2. Tạo (hoặc sửa) file `CLAUDE.md` (đối với Claude) hoặc `KILO.md` (đối với Kilo) ở thư mục gốc, dán nội dung sau vào:
+
+```md
+# System Instructions
+Bạn đang chạy bằng **AI Developer Skill OS** (Tác giả: Quang Khánh).
+
+Vui lòng tìm đọc danh sách kỹ năng tại file `./rules-skill/skills.json`.
+Trước khi thực hiện bất kỳ yêu cầu nào, hãy gọi file `SKILL.md` tương ứng trong thư mục `./rules-skill/skills/` để biết quy trình làm việc chuẩn.
+Luôn giao tiếp bằng tiếng Việt nhưng viết code, đặt tên biến, comment trong code bằng tiếng Anh.
+```
+
+### Cho Cursor / Windsurf (AI Code Editors)
+Cursor và Windsurf sử dụng file quy tắc riêng biệt.
+**Cách cài đặt:**
+1. Copy toàn bộ thư mục `rules-skill/` vào gốc dự án của bạn.
+2. Mở file `.cursorrules` (với Cursor) hoặc `.windsurfrules` (với Windsurf), dán nội dung sau vào:
+
+```md
+# AI Developer Skill OS by Quang Khánh
+
+When answering or generating code, you MUST act as an expert engineer using the skills defined in `./rules-skill/skills.json`.
+Always read the relevant `SKILL.md` from `./rules-skill/skills/` before providing a solution.
+Speak to me in Vietnamese, but write all code in English.
+```
+
+---
+
+## 3. Cách tương tác với AI
+
+Vì AI giờ đây đã có "nghề" (Skill), bạn không cần phải prompt quá dài dòng. Hãy ra lệnh như giao việc cho một kỹ sư.
+
+**Ví dụ 1: Nhờ AI tự lên kế hoạch (Kích hoạt `agent-orchestrator`)**
+> "Quang Khánh ơi, dự án này đang cần thêm tính năng Đăng nhập. Cậu lên kế hoạch giúp mình nên làm gì trước nhé."
+
+**Ví dụ 2: Sửa lỗi (Kích hoạt `bug-fix`)**
+> "Bị lỗi Hydration error trên Next.js rồi. Fix giúp mình."
+
+**Ví dụ 3: Review Codebase (Kích hoạt `project-audit`)**
+> "Audit nhanh cho tôi thư mục `src/components/`, tìm xem có bị vấn đề về hiệu năng hay code smell không."
+
+**Ví dụ 4: Frontend UI (Kích hoạt `ui-builder` + `design-system`)**
+> "Làm cho tôi cái giao diện màn hình Danh sách User. Chú ý dùng chuẩn components của thư mục `src/components/ui/` nhé."
+
+**Ví dụ 5: Tích hợp API (Kích hoạt `api-integration`)**
+> "Tích hợp cái swagger login này vào frontend giúp. Nhớ dùng React Query như chuẩn của project."
+
+---
+
+## 4. Tùy chỉnh Skin (Dành cho Advanced User)
+
+Nếu bạn muốn thêm kỹ năng mới cho AI, hãy sử dụng mẫu (Template) đã được tác giả chuẩn bị sẵn:
+1. Copy file từ thư mục `_template/SKILL.md`.
+2. Chỉnh sửa các thông số: Name, Description, Trigger, Scope, v.v.
+3. Đăng ký nó vào file `skills.json` ở gốc.
+4. Tận hưởng AI với kỹ năng mới của riêng bạn!
+
+---
+
+Để xem danh sách chi tiết và công dụng của từng skill, vui lòng xem [Chi Tiết Skills](CHI_TIET_SKILLS.md).

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "ai-developer-skill-os",
+  "version": "1.0.0",
+  "description": "Multi-agent skill package cho AI coding agents (Claude, Cursor, Windsurf, Antigravity) với 23 skills chuyên nghiệp.",
+  "main": "bin/install.js",
+  "bin": {
+    "ai-developer-skill-os": "bin/install.js",
+    "ai-skill": "bin/install.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phamquangkhanh2999/ai-developer-skill-os.git"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "cursor",
+    "windsurf",
+    "skills",
+    "developer",
+    "agent",
+    "prompts",
+    "framework"
+  ],
+  "author": "Quang Khánh",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/phamquangkhanh2999/ai-developer-skill-os/issues"
+  },
+  "homepage": "https://github.com/phamquangkhanh2999/ai-developer-skill-os#readme"
+}

package/skills/backend/auth-security/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: auth-security
+description: >-
+  Triển khai tính năng đăng nhập (JWT, OAuth), phân quyền (RBAC) và bảo vệ app khỏi các lỗ hổng OWASP.
+version: 1.0.0
+category: backend
+tags: [auth, security, jwt, oauth, rbac, owasp]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Auth & Security Engineer
+
+> **Language rule:**
+> Use **English** for: security protocols, tokens, headers, algorithms, code.
+> Use **the user's language** for: explanations, summaries, and questions.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User asks to "add login", "protect this route", or "implement OAuth"
+- Defining user roles and permissions (Admin vs User)
+- Project audit flags security vulnerabilities (P0/P1)
+- Handling sensitive data (passwords, PII, API keys)
+
+---
+
+## Scope
+
+- ✅ **Authentication:** JWT, Session Cookies, OAuth2 (Google, GitHub, etc.), Magic Links.
+- ✅ **Authorization:** Role-Based Access Control (RBAC), Middleware guards.
+- ✅ **Data Protection:** Hashing passwords (bcrypt, Argon2), encrypting sensitive fields.
+- ✅ **Vulnerability Prevention:** CSRF protection, Rate Limiting, CORS config, input sanitization (SQLi/XSS).
+
+---
+
+## Non-goals
+
+- ❌ Do NOT store passwords in plain text. Ever.
+- ❌ Do NOT hardcode secrets or private keys in the code (use `.env`).
+- ❌ Do NOT store JWTs in `localStorage` if cookies (`httpOnly`) are an option, unless explicitly requested.
+
+---
+
+## Workflow
+
+### Phase 1 — Strategy Selection
+
+Determine the auth mechanism:
+1. **Stateless (JWT):** Good for mobile/SPAs, distributed systems.
+2. **Stateful (Sessions):** Good for traditional web apps, easier revocation.
+3. **Third-party (OAuth / Auth0 / NextAuth / Supabase):** Offload auth complexity.
+
+### Phase 2 — Implementation
+
+**For JWT + Cookies (Recommended Web Pattern):**
+1. Create Login endpoint: Verify password → Generate JWT → Set `httpOnly` cookie.
+2. Create Middleware: Extract cookie → Verify JWT signature → Attach user to request.
+3. Create Logout endpoint: Clear the cookie.
+
+**For Authorization:**
+1. Define roles (e.g., `enum Role { ADMIN, USER }`).
+2. Create Role Middleware: Check `req.user.role`.
+
+### Phase 3 — Security Audit
+
+Verify:
+- Passwords are hashed with a salt (e.g., `bcrypt.hash(password, 10)`).
+- Cookies are `httpOnly`, `Secure` (in prod), and `SameSite`.
+- CORS is configured to only allow trusted origins.
+
+---
+
+## Output Format
+
+```
+🛡️ Auth & Security Report
+─────────────────────────────────────────────────
+Mechanism:  [JWT in httpOnly Cookie / OAuth / Session]
+Roles:      [Admin, User]
+
+Components Implemented:
+  ✅ Login/Logout handlers
+  ✅ Auth Middleware (Guard)
+  ✅ Password hashing (bcrypt)
+
+Security measures enforced:
+  • `httpOnly`, `Secure`, `SameSite=Strict` on cookies
+  • CORS restricted to frontend origin
+
+🔗 Next Steps:
+  Remember to add `JWT_SECRET` to your production environment variables.
+```

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

@@ -0,0 +1,123 @@
+---
+name: backend-architecture
+description: >-
+  Kiểm soát cấu trúc backend, ép buộc tuân thủ mô hình Layer (Controller/Service/Repository) và vị trí file.
+version: 1.0.0
+category: backend
+tags: [architecture, backend, controller, service, repository, structure]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Backend Architecture
+
+> **Language rule:**
+> Use **English** for: code, folder names, pattern names, technical rules.
+> Use **the user's language** for: explanations, summaries, and questions.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- Creating new backend API endpoints, services, or models
+- User asks "where should I put this business logic?"
+- Project audit flags mixed concerns (e.g., SQL queries inside a controller)
+- Inheriting or setting up a Node.js, Python, or Go backend
+
+---
+
+## Scope
+
+- ✅ Discover existing backend folder structure
+- ✅ Enforce Layered Architecture (Controller → Service → Data Access)
+- ✅ Enforce Domain/Module-based structure if applicable (`src/users/`, `src/orders/`)
+- ✅ Define where validation, mapping, and error handling should live
+- ✅ Validate file placement before code generation
+
+---
+
+## Non-goals
+
+- ❌ Do NOT rewrite the architecture unless requested
+- ❌ Do NOT write the actual database queries (delegate to `database-engineer`)
+- ❌ Do NOT configure server infrastructure (delegate to `deployment`)
+
+---
+
+## Severity Levels
+
+| Level | Meaning |
+|-------|---------|
+| P0 | Circular dependency or security bypass in architecture |
+| P1 | Mixed concerns (e.g., ORM logic in route handler) |
+| P2 | Inconsistent folder or file naming |
+| P3 | Minor deviation from convention |
+
+---
+
+## Workflow
+
+### Phase 1 — Architecture Discovery
+
+Analyze the project structure:
+1. **Classic MVC / Layered:** `controllers/`, `services/`, `models/`, `routes/`
+2. **Domain-Driven (Module):** `src/modules/user/{controller, service, repository}`
+3. **Framework-specific:** NestJS (`.controller.ts`, `.service.ts`), Django apps, Express monolithic.
+4. **Serverless:** `functions/`, `handlers/`
+
+---
+
+### Phase 2 — Rule Extraction
+
+Extract conventions:
+- **Routes/Controllers:** Should only handle HTTP req/res, params validation, and calling services. No business logic.
+- **Services:** Pure business logic. Does not know about HTTP (`req`/`res`).
+- **Repositories/Data Access:** Only layer that interacts with the DB.
+- **Error Handling:** Centralized error middleware vs local try/catch.
+
+---
+
+### Phase 3 — File Placement & Routing
+
+Map a new requirement to the architecture:
+
+*Request: "Add an endpoint to update user profile"*
+- Route: `PUT /api/users/:id` mapped in `src/routes/user.routes.ts`
+- Controller: `updateProfile(req, res)` in `src/controllers/user.controller.ts`
+- Service: `updateUserProfile(userId, data)` in `src/services/user.service.ts`
+
+---
+
+## Decision Tree
+
+```
+Does the project group files by Layer or by Domain?
+  ├── Layer  → Place in `src/controllers/` and `src/services/`
+  └── Domain → Place in `src/modules/users/`
+
+Where does data validation happen?
+  ├── Middleware → Add Zod/Joi validation at the router level
+  └── Controller → Validate inside the controller function before calling service
+```
+
+---
+
+## Output Format
+
+```
+🏗️ Backend Architecture Plan
+─────────────────────────────────────────────────
+Structure Type: [Layered / Domain-based / Framework-specific]
+
+Layer Mapping:
+  ✅ Controller: [path/to/controller.ts] — handles HTTP
+  ✅ Service:    [path/to/service.ts] — business logic
+  ✅ Repo/DB:    [handled by database-engineer]
+
+⚠️ Constraints enforced:
+  • Do not pass `req` or `res` objects into the Service layer.
+  • Validate all inputs at the Controller/Route level.
+
+🔗 Next Steps:
+  Proceeding to implement the layers.
+```

package/skills/backend/database-engineer/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: database-engineer
+description: >-
+  Thiết kế database schema, viết script migration và tối ưu truy vấn cho SQL/NoSQL bằng ORM (Prisma, Drizzle...).
+version: 1.0.0
+category: backend
+tags: [database, sql, prisma, drizzle, schema, migration, query-optimization]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Database Engineer
+
+> **Language rule:**
+> Use **English** for: table names, columns, queries, ORM code, technical terms.
+> Use **the user's language** for: explanations, summaries, and questions.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User says "create a new table", "add a column", "design the schema"
+- Writing complex data retrieval logic (joins, aggregations)
+- A query is running slowly and needs optimization (indexing)
+- Running or generating database migrations
+
+---
+
+## Scope
+
+- ✅ **Schema Design:** Model tables, relations (1:1, 1:N, N:M), and constraints (Unique, FK).
+- ✅ **ORM Integration:** Generate code for Prisma, Drizzle, TypeORM, Sequelize, or Mongoose.
+- ✅ **Migrations:** Generate SQL or ORM migration files safely.
+- ✅ **Query Optimization:** Prevent N+1 queries, add indexes, use efficient aggregations.
+
+---
+
+## Non-goals
+
+- ❌ Do NOT execute destructive migrations (DROP TABLE) on production environments without extreme warnings and approval.
+- ❌ Do NOT mix raw SQL into ORM logic unless necessary for performance.
+
+---
+
+## Workflow
+
+### Phase 1 — Schema Design
+
+Understand the business entities and relations.
+- Identify primary keys (UUID vs Auto-increment ID).
+- Identify foreign keys and cascade rules (`ON DELETE CASCADE`).
+- Ensure proper normalization (usually 3NF) or denormalization (if NoSQL).
+
+### Phase 2 — ORM / Migration Generation
+
+Map the design to the project's tool:
+- **Prisma:** Update `schema.prisma`.
+- **Drizzle:** Update `schema.ts`.
+- **Raw SQL:** Write `V1__create_table.sql`.
+
+### Phase 3 — Query Implementation
+
+Write the data access methods (Repository pattern or direct ORM calls).
+- Avoid fetching `SELECT *` if only 2 columns are needed.
+- Batch queries or use joins to prevent N+1 issues.
+
+---
+
+## Decision Tree
+
+```
+Is the project using an ORM?
+  ├── Prisma  → Modify `schema.prisma`, use `prisma.entity.findMany()`
+  ├── Drizzle → Modify schema TS files, use Drizzle query builder
+  └── No      → Write raw SQL or use query builder (Knex)
+
+Does the schema change drop data or alter existing columns?
+  ├── Yes → Flag as High Risk. Provide rollback strategy. Ask for approval.
+  └── No  → Standard migration (e.g., adding a nullable column).
+```
+
+---
+
+## Output Format
+
+```
+🗄️ Database Engineering Report
+─────────────────────────────────────────────────
+Action:     [Schema Update / Query Optimization]
+Tooling:    [Prisma / Raw SQL / etc.]
+
+Changes:
+  ✅ Added model: `User` (1:N with `Post`)
+  ✅ Added index on `User.email`
+  ✅ Generated query: `getUserWithPosts`
+
+⚠️ Risk Assessment:
+  [Low / High — e.g., "Safe addition, no data loss"]
+
+🔗 Next Steps:
+  Run `npx prisma migrate dev` to apply these changes locally.
+```

package/skills/backend/deployment/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: deployment
+description: >-
+  Cấu hình CI/CD pipelines, tạo Dockerfile và thiết lập môi trường để deploy lên Vercel, AWS hoặc VPS.
+version: 1.0.0
+category: backend
+tags: [deploy, ci-cd, docker, github-actions, devops, hosting]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Deployment & DevOps
+
+> **Language rule:**
+> Use **English** for: configuration files, Docker commands, YAML syntax, technical concepts.
+> Use **the user's language** for: explanations, summaries, and questions.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User asks "how do I deploy this?", "create a Dockerfile", or "setup CI/CD"
+- Configuring GitHub Actions, GitLab CI, or Jenkins
+- Preparing a project for Vercel, Netlify, Render, or AWS
+- Setting up environment variables for production
+
+---
+
+## Scope
+
+- ✅ **Containerization:** Write `Dockerfile` and `docker-compose.yml`.
+- ✅ **CI/CD Pipelines:** Write GitHub Actions YAML for testing, building, and deploying.
+- ✅ **Environment Setup:** Create `.env.example` and document required production variables.
+- ✅ **Build Scripts:** Ensure `package.json` has correct build and start commands.
+
+---
+
+## Non-goals
+
+- ❌ Do NOT expose real production secrets. Always use placeholders or CI secrets.
+- ❌ Do NOT over-complicate (e.g., don't setup Kubernetes if a simple Docker container on a VPS is enough).
+
+---
+
+## Workflow
+
+### Phase 1 — Platform Selection
+
+Ask the user where they are deploying (if not specified):
+1. **PaaS (Vercel, Render, Heroku):** Very easy, mostly relies on `vercel.json` or standard build scripts. No Docker needed usually.
+2. **VPS/VM (DigitalOcean, AWS EC2):** Needs Docker and/or PM2 + Nginx reverse proxy.
+3. **Container Service (AWS ECS, Google Cloud Run):** Needs a highly optimized Dockerfile.
+
+### Phase 2 — Containerization (If required)
+
+Create a multi-stage Dockerfile for minimal image size:
+1. `deps` stage: Install dependencies.
+2. `builder` stage: Build the app.
+3. `runner` stage: Copy only the built assets and prod modules, start the app.
+
+### Phase 3 — CI/CD Pipeline
+
+Create `.github/workflows/deploy.yml`:
+- Trigger on `push` to `main`.
+- Job 1: Setup Node/Python/Go, install deps, run tests, run linter.
+- Job 2: Build image and push to registry, or deploy to PaaS.
+
+### Phase 4 — Environment Variables
+
+Audit the codebase for `process.env.XYZ` and create a `.env.example` file listing every required variable.
+
+---
+
+## Output Format
+
+```
+🚀 Deployment Plan
+─────────────────────────────────────────────────
+Target:     [Vercel / Docker VPS / AWS]
+Tooling:    [GitHub Actions, Docker]
+
+Files Created/Modified:
+  ✅ `Dockerfile` (Multi-stage build)
+  ✅ `.github/workflows/deploy.yml`
+  ✅ `.env.example`
+
+⚠️ Prerequisites:
+  Before deploying, you must set these secrets in GitHub Actions:
+  - `DOCKER_USERNAME`
+  - `DATABASE_URL`
+
+🔗 Next Steps:
+  Commit these files and push to `main` to trigger the pipeline.
+```