Skill AI App

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

Build, scaffold và mở rộng AI App dựa trên MCP với @v-miniapp/cli và các module @v-miniapp/ai — server, web widgets, và imperative APIs.

Tính năng

• MCP Server — Build tools, resources, prompts và skills với @v-miniapp/ai/server
• React Widgets — Host-aware UI với hooks cho tool results, state và follow-up messages qua @v-miniapp/ai/web
• Imperative APIs — Non-React bridge integration với @v-miniapp/ai/apis
• CLI Tooling — Scaffold từ templates, dev server với inspector, build và deploy qua @v-miniapp/cli
• Skill Authoring — Đóng gói và đăng ký bundled skills với SKILL.md frontmatter
• Best Practices — MCP design patterns, tool naming, response contracts, transport strategy

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

Phát triển AI App trên nền tảng MCP có nhiều khái niệm và module cần nắm vững:

• MCP Server phức tạp: Cần hiểu cách khai báo tools, resources, prompts và cách chúng tương tác với nhau.
• Widget rendering: React widgets trong AI App có cơ chế riêng — cần hiểu hooks, state management và cách giao tiếp với server.
• Structured content: Server và widget giao tiếp qua structured content — cần tuân thủ đúng response contracts.
• Skill authoring: Viết và đóng gói skills có quy tắc riêng về cấu trúc SKILL.md và frontmatter.

Skill AI App giúp AI agent hiểu toàn bộ kiến trúc AI App, từ đó hỗ trợ lập trình viên xây dựng MCP server, tạo widgets và tích hợp các module một cách chính xác.

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/ai-app-skills

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

# Cài cho agent cụ thể
npx skills add v-open-platform/ai-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/ai-app-skills.git
cp -r ai-app-skills/skills/ai-app ~/.claude/skills/

Cho project-level:

mkdir -p .claude/skills
cp -r ai-app-skills/skills/ai-app .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-cli create my-ai-app --ai-app --ai-template ai-app-blank
cd my-ai-app && pnpm install && pnpm run dev

Tổng quan kiến trúc

┌─────────────────────────────────────────┐
│              AI App Project             │
├──────────┬──────────┬───────────────────┤
│  server/ │   web/   │     skills/       │
│          │          │                   │
│ McpServer│  Widgets │  SKILL.md files   │
│ Tools    │  Hooks   │  Bundled skills   │
│ Resources│  State   │                   │
│ Prompts  │  i18n    │                   │
└──────────┴──────────┴───────────────────┘
     ↕            ↕
@v-miniapp/ai  @v-miniapp/ai
   /server        /web & /apis

Các module chính

Module	Package	Mô tả
Server	@v-miniapp/ai/server	MCP server với tools, resources, prompts, skills
Web	@v-miniapp/ai/web	React hooks cho widgets (useToolInfo, useCallTool, renderWidget)
APIs	@v-miniapp/ai/apis	Imperative bridge cho non-React integration
CLI	@v-miniapp/cli	Project scaffolding, dev server, inspector, build

Cấu trúc Skill

ai-app/
├── SKILL.md                          # File skill chính
└── references/
    ├── best-practices.md             # MCP design patterns & quality checklist
    ├── cli.md                        # v-cli commands & project bootstrap
    ├── server.md                     # McpServer, tools, resources, prompts
    ├── web.md                        # React widget hooks & rendering
    ├── apis.md                       # Imperative bridge API reference
    ├── skill.md                      # Skill authoring & SKILL.md format
    └── project-structure.md          # Project layout & app-config.json

Các prompt hữu ích

Tạo MCP Server

Tạo AI app với một tool quản lý todo list và widget hiển thị danh sách

Thêm một MCP tool mới để fetch dữ liệu thời tiết

Xây dựng Widget

Build một widget hiển thị kết quả tìm kiếm từ tool của tôi

Thêm follow-up message flow vào widget

Skill Authoring

Đăng ký một skill cho các tools quản lý task

Tạo SKILL.md với frontmatter cho skill mới

Tích hợp và Debug

Kết nối widget với MCP server qua structured content

Debug lỗi transport giữa server và widget

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

mẹo

• Nêu rõ loại module: Cho AI biết bạn đang làm việc với server, web widget hay APIs.
• Mô tả data flow: Giải thích dữ liệu chảy từ tool → server → widget như thế nào.
• Chỉ rõ response format: Nếu tool cần trả structured content, mô tả cấu trúc mong muốn.
• Đề cập error handling: Yêu cầu xử lý lỗi transport, timeout và fallback scenarios.

Skill liên quan

Skill	Mô tả
MiniApp	CLI tooling, build/deploy, native APIs với @v-miniapp/cli và @v-miniapp/apis
UI React	UI components, routing, theming, design tokens với @v-miniapp/ui-react