Chuyển tới nội dung chính

Skill MiniApp

GitHub: v-open-platform/v-mini-app-skills

Tạo, chạy, build và deploy V Mini App với @v-miniapp/cli và tích hợp các tính năng native với @v-miniapp/apis.

Tính năng​

  • CLI Tooling — Scaffold, dev server, build và deploy với @v-miniapp/cli
  • JavaScript APIs — Auth, storage, payment, location, camera, QR scan, biometrics, ... thông qua @v-miniapp/apis
  • Native Capabilities — Truy cập tính năng thiết bị: gọi điện, upload/download file, Bluetooth beacons
  • Non-Interactive CLI — Hỗ trợ AI agent chạy lệnh tự động hoàn toàn
  • Dev & Deploy Flow — Hot reload, production build và deploy lên V-App bằng một lệnh

Tại sao cần skill này?​

Phát triển MiniApp đòi hỏi lập trình viên phải nắm rõ hệ thống API nền tảng, vòng đời ứng dụng, và các quy tắc riêng của V-App. Một số thách thức thường gặp:

  • Hệ thống API phong phú: MiniApp có hàng chục API (storage, network, payment, location, camera, v.v.) — khó nhớ hết cách sử dụng và xử lý lỗi.
  • Vòng đời phức tạp: Cần hiểu rõ thứ tự các sự kiện onLaunch, onShow, onHide để quản lý trạng thái đúng cách.
  • Quyền truy cập: Nhiều API yêu cầu xin quyền từ người dùng, cần xử lý đúng luồng cấp/từ chối quyền.
  • Tích hợp thanh toán: Luồng thanh toán có nhiều bước và cần tuân thủ chặt chẽ quy trình của nền tảng.

Skill MiniApp giúp AI agent hiểu sâu về nền tảng MiniApp, từ đó hỗ trợ lập trình viên viết code đúng chuẩn, xử lý đầy đủ các trường hợp ngoại lệ và tuân thủ best practices.

Cài đặt​

Cách 1: Sử dụng skills CLI (Khuyến nghị)​

# Cài vào project hiện tại
npx skills add v-open-platform/v-mini-app-skills

# Cài global
npx skills add v-open-platform/v-mini-app-skills -g

# Cài cho agent cụ thể
npx skills add v-open-platform/v-mini-app-skills -a claude-code

Cách 2: Cài đặt thủ công​

Cho Claude Code:

git clone https://github.com/v-open-platform/v-mini-app-skills.git
cp -r v-mini-app-skills/skills/v-miniapp ~/.claude/skills/

Cho project-level:

mkdir -p .claude/skills
cp -r v-mini-app-skills/skills/v-miniapp .claude/skills/
mẹo

Xem thêm danh sách agent được hỗ trợ để biết thư mục cài đặt cho từng agent.

Bắt đầu nhanh​

npm install -g @v-miniapp/cli
v-miniapp-cli login
v-miniapp-cli create my-app && cd my-app && v-miniapp-cli dev

Cấu trúc Skill​

v-miniapp/
├── SKILL.md                          # File skill chính
└── references/
    ├── user-intent.md                # Hướng dẫn nhận diện yêu cầu
    ├── basic-setup.md                # Dev, build, deploy & app config
    ├── ai-guidelines/
    │   ├── cli.md                    # Hướng dẫn CLI automation
    │   └── jsapi.md                  # Hướng dẫn sử dụng JSAPI
    ├── cli/
    │   └── commands.md               # Tham khảo CLI commands
    └── jsapi/
        ├── basic.md                  # System info & exit
        ├── open.md                   # Auth & app opening
        ├── payment.md                # Xử lý thanh toán
        ├── storage.md                # Local storage
        ├── network.md                # HTTP requests
        ├── feedback.md               # Dialogs, toasts, loading
        ├── location.md               # Geolocation
        ├── image.md                  # Image picker & compression
        ├── file-network.md           # File upload/download
        ├── phone.md                  # Gọi điện
        ├── biometrics.md             # Fingerprint/Face ID
        ├── bluetooth.md              # Beacon discovery
        ├── scan-qr.md               # QR code scanning
        └── share-app.md             # Chia sẻ ứng dụng

Các prompt hữu ích​

Quản lý vòng đời​

Thiết lập vòng đời cho MiniApp: khi khởi động thì kiểm tra token, khi hiển thị lại thì refresh dữ liệu, khi ẩn thì lưu trạng thái
Xử lý trường hợp người dùng mở lại MiniApp sau khi đã bị kill process

Gọi API và xử lý dữ liệu​

Viết hàm gọi API lấy danh sách sản phẩm có phân trang, xử lý loading và lỗi mạng
Tạo service layer gọi backend API với interceptor tự động refresh token khi hết hạn

Lưu trữ dữ liệu​

Tạo module quản lý giỏ hàng sử dụng Storage API: thêm, xoá, cập nhật số lượng, tính tổng tiền
Lưu cache danh sách sản phẩm vào storage, tự động hết hạn sau 5 phút

Thanh toán​

Tích hợp luồng thanh toán: tạo đơn hàng, gọi API thanh toán, xử lý callback thành công/thất bại
Xử lý các trường hợp lỗi trong luồng thanh toán: timeout, huỷ giao dịch, lỗi mạng

Quyền truy cập và thiết bị​

Xin quyền truy cập camera, xử lý trường hợp người dùng từ chối, hiển thị hướng dẫn bật lại quyền
Lấy vị trí hiện tại của người dùng, fallback sang nhập địa chỉ thủ công nếu không có quyền GPS

Điều hướng​

Thiết lập hệ thống điều hướng cho MiniApp với các trang: trang chủ, danh sách, chi tiết, giỏ hàng, thanh toán
Xử lý deep link: khi người dùng mở MiniApp từ link chia sẻ, điều hướng đúng đến trang chi tiết sản phẩm

Debug và tối ưu​

Kiểm tra và tối ưu hiệu suất trang danh sách sản phẩm: giảm re-render, lazy load ảnh, phân trang
Thêm logging cho các API call để dễ debug trên môi trường thực tế

Mẹo viết prompt hiệu quả​

mẹo
  • Nêu rõ luồng nghiệp vụ: Mô tả cụ thể các bước trong luồng xử lý, AI sẽ sinh code đầy đủ hơn.
  • Đề cập xử lý lỗi: Yêu cầu AI xử lý các trường hợp ngoại lệ (mất mạng, hết phiên, từ chối quyền).
  • Chỉ rõ API cần dùng: Nếu biết API nào phù hợp, hãy đề cập trong prompt để AI sử dụng đúng.
  • Mô tả ngữ cảnh: Cho AI biết trang/component hiện tại đang làm gì để nhận được gợi ý phù hợp nhất.

Skill liên quan​

SkillMô tả
UI ReactUI components, routing, theming, design tokens với @v-miniapp/ui-react
AI AppMCP-based AI apps với @v-miniapp/ai server/web/apis modules