Hướng dẫn Tạo Skill

Hướng dẫn cách tạo, kiểm thử và publish skill ODC-X của riêng bạn.

Skill là gì?

Skill là một file markdown có cấu trúc (SKILL.md) chứa hướng dẫn cho AI assistant. Skill được đóng gói thành npm module và phân phối qua registry ODC-X.

Bắt đầu nhanh

1. Tạo thư mục Skill

mkdir -p my-skill
cd my-skill

2. Tạo `SKILL.md`

---
name: my-skill
description: "Mô tả một câu về skill và khi nào nên dùng"
metadata:
  author: Tên của bạn
  version: "1.0.0"
  last_updated: "2026-01-01"
  category: code-generation
  tags: "tag1, tag2, tag3"
---

# Tên Skill

## Tổng quan

Giải thích skill làm gì và triết lý cốt lõi trong 2–3 câu.

## Khi nào nên dùng

- Các điều kiện kích hoạt
- Yêu cầu người dùng nên gọi skill này
- Ví dụ: "làm X", "giúp tôi Y"

## Yêu cầu trước

- AI cần những context gì?
- File hoặc dữ liệu cần có?

## Hướng dẫn

### Bước 1: Thu thập Context
...

### Bước 2: Áp dụng Skill
...

### Bước 3: Xuất kết quả
...

## Định dạng đầu ra

Mô tả cấu trúc đầu ra mong đợi.

## Ví dụ

### Đầu vào mẫu
...

### Đầu ra mẫu
...

3. Tạo `package.json`

{
  "name": "@odcx/my-skill",
  "version": "1.0.0",
  "description": "Mô tả một câu về skill",
  "main": "SKILL.md",
  "keywords": ["odcx-skill", "ai", "tag1"],
  "author": "Tên của bạn <email@fpt.com>",
  "license": "Internal",
  "publishConfig": {
    "registry": "https://pkgs.dev.azure.com/FPT-Software/_packaging/odcx-skills/npm/registry/"
  }
}

Tài liệu tham khảo định dạng SKILL.md

Frontmatter (YAML)

Trường	Bắt buộc	Mô tả
`name`	✓	Định danh kebab-case duy nhất
`description`	✓	Mô tả một câu để hiển thị trên marketplace. Nên bao gồm cụm từ kích hoạt.
`metadata.author`	✓	Tên đầy đủ tác giả
`metadata.version`	✓	Phiên bản semantic (vd: `"1.0.0"`)
`metadata.last_updated`	✓	Chuỗi ngày ISO
`metadata.category`	✓	Một trong: `code-generation`, `code-review`, `architecture`, `testing`, `security`, `devops`, `planning`, `documentation`, `other`
`metadata.tags`	✓	Tags phân cách bởi dấu phẩy để tìm kiếm
`license`	—	Ghi chú về giấy phép

Các mục bắt buộc

Mỗi skill nên có các mục sau:

Tổng quan — Mục đích và triết lý (2–4 câu)
Khi nào nên dùng — Điều kiện kích hoạt và ý định người dùng
Yêu cầu trước — Context và đầu vào cần thiết
Hướng dẫn — Hướng dẫn thực thi từng bước
Định dạng đầu ra — Kết quả mong đợi

Các mục tùy chọn

Ví dụ — Mẫu đầu vào/đầu ra
Skill liên quan — Liên kết tới skill bổ sung
Giới hạn — Các ràng buộc đã biết

Viết hướng dẫn hiệu quả

Hãy cụ thể

❌ "Phân tích code"
✓ "Đọc tất cả file trong src/ và xác định các hàm dài hơn 30 dòng"

Dùng bước đánh số

AI thực thi hướng dẫn tuần tự. Đánh số các bước:

### Bước 1: Tải Context
Đọc file tại đường dẫn được cung cấp.

### Bước 2: Áp dụng phân tích
Với mỗi hàm, kiểm tra:
- Số dòng code (gắn cờ nếu > 30)
- Độ phức tạp cyclomatic
...

Xác định cấu trúc đầu ra

Định nghĩa chính xác AI cần tạo ra gì:

## Định dạng đầu ra

Tạo báo cáo markdown với:
1. **Tóm tắt** — đoạn tổng quan
2. **Vấn đề tìm thấy** — bảng với cột: File, Dòng, Mức độ, Mô tả
3. **Khuyến nghị** — danh sách đánh số

Dùng logic có điều kiện

Nếu codebase dùng TypeScript:
  - Kiểm tra kiểu `any`
  - Xác minh strict mode đã bật

Nếu codebase dùng JavaScript:
  - Kiểm tra JSDoc còn thiếu

Publish Skill

Yêu cầu trước

Tài khoản Azure DevOps với quyền ghi vào feed odcx-skills
npm đã xác thực với feed:

npm config set @odcx:registry https://pkgs.dev.azure.com/FPT-Software/_packaging/odcx-skills/npm/registry/
npm login --registry=https://pkgs.dev.azure.com/FPT-Software/_packaging/odcx-skills/npm/registry/

Publish

npm publish

Quản lý phiên bản

Tuân theo semantic versioning:

Patch (1.0.1): Sửa lỗi chính tả, cải thiện diễn đạt nhỏ
Minor (1.1.0): Thêm mục mới, thêm hướng dẫn, tương thích ngược
Major (2.0.0): Tái cấu trúc hoàn toàn, thay đổi phá vỡ tương thích

Kiểm thử Skill

Trước khi publish, kiểm thử skill thủ công:

Thêm thư mục skill cục bộ làm nguồn và đồng bộ:

odcx source add test-local --local-path /path/to/ODCX-Skills
odcx source sync test-local

Cài đặt skill theo tên:
```
odcx skill install my-skill
```
Mở dự án với context phù hợp

Gọi skill với AI assistant:

Sử dụng skill my-skill, [mô tả tác vụ]

Xác minh đầu ra khớp với định dạng đã chỉ định
Kiểm thử các trường hợp biên:
- Đầu vào rỗng
- File lớn
- Cấu trúc dự án không chuẩn

Vòng đời Skill

Bản nháp → Review → Đã publish → Không dùng nữa

Bản nháp: Đang phát triển, chưa publish
Review: Đang được peer review trước khi publish
Đã publish: Có thể tìm thấy trên marketplace
Không dùng nữa: Đã có skill mới thay thế; vẫn cài được nhưng không được khuyến nghị

Tiêu chuẩn cộng đồng

Giữ skill tập trung vào một tác vụ cụ thể
Viết hướng dẫn hoạt động không cần context bổ sung
Bao gồm ít nhất 2 ví dụ cụ thể
Tránh hard-code đường dẫn hoặc tên dự án cụ thể
Ưu tiên tên biến mô tả rõ ràng trong hướng dẫn

Hỗ trợ

Mở issue trong repository ODCX-Skills
Đăng câu hỏi trong kênh #odcx-skills trên Teams
Tham khảo các skill có sẵn trong ODCX-Skills/skills/ để nắm bắt mẫu chuẩn

Skill là gì?​

Bắt đầu nhanh​

1. Tạo thư mục Skill​

2. Tạo SKILL.md​

3. Tạo package.json​

Tài liệu tham khảo định dạng SKILL.md​

Frontmatter (YAML)​

Các mục bắt buộc​

Các mục tùy chọn​

Viết hướng dẫn hiệu quả​

Hãy cụ thể​

Dùng bước đánh số​

Xác định cấu trúc đầu ra​

Dùng logic có điều kiện​

Publish Skill​

Yêu cầu trước​

Publish​

Quản lý phiên bản​

Kiểm thử Skill​

Vòng đời Skill​

Tiêu chuẩn cộng đồng​

Hỗ trợ​