Khai báo Skills

Skill là tập hướng dẫn dạng văn bản cho AI agent, mô tả agent nên làm gì và sử dụng những tool nào trong một tình huống cụ thể. Mỗi skill tương ứng với một file SKILL.md trong thư mục skills/ của project.

Cấu trúc thư mục

<app-root>/
└── skills/
    ├── search-products/
    │   └── SKILL.md
    └── checkout/
        └── SKILL.md

---

Format SKILL.md

File SKILL.md gồm hai phần: YAML frontmatter (metadata) và nội dung markdown (hướng dẫn cho agent).

skills/search-products/SKILL.md

---
name: search-products
description: Hỗ trợ người dùng tìm kiếm sản phẩm theo từ khoá và danh mục
metadata:
  binding-tools:
    - search-products
    - get-product-detail
---

## Hướng dẫn tìm kiếm sản phẩm

Khi người dùng muốn tìm kiếm sản phẩm:

1. Hỏi người dùng về từ khoá hoặc danh mục muốn tìm.
2. Sử dụng tool `search-products` để lấy danh sách kết quả.
3. Hiển thị kết quả và hỏi người dùng có muốn xem chi tiết sản phẩm nào không.
4. Nếu người dùng muốn xem chi tiết, dùng tool `get-product-detail`.

Giải thích các trường frontmatter

Trường	Bắt buộc	Mô tả
name	✅	Tên định danh duy nhất của skill
description	✅	Mô tả ngắn, agent dùng để hiểu khi nào kích hoạt skill này
metadata.binding-tools		Danh sách tool liên quan đến skill — agent sẽ ưu tiên dùng các tool này

mẹo

Phần nội dung markdown (body) là hướng dẫn dành cho AI agent. Viết càng rõ ràng, agent càng hoạt động chính xác theo ý muốn.

---

Đăng ký Skill lên Server

Sau khi tạo file SKILL.md, đăng ký skill vào MCP Server:

server/src/index.ts

import { McpServer } from '@v-miniapp/ai/server'

const server = new McpServer()

// Cách 1: string shorthand
server.registerSkill('search-products')

// Cách 2: object config
server.registerSkill({ name: 'search-products' })

// Cách 3: mảng nhiều skills (có thể mix string và object)
server.registerSkills(['search-products', 'checkout'])
server.registerSkills([{ name: 'search-products' }, 'checkout'])

server.run()

ghi chú

Tên truyền vào registerSkill phải khớp với tên thư mục trong skills/ và với trường name trong frontmatter của SKILL.md.

---

Cách hoạt động

Khi server khởi động, mỗi skill sẽ được expose dưới dạng resource với URI skill://<name>. AI agent có thể đọc nội dung skill này để hiểu ngữ cảnh và hành động phù hợp.

skill://search-products  →  skills/search-products/SKILL.md
skill://checkout         →  skills/checkout/SKILL.md