🐢 Kim Quy

Quản lý Profiles và Skills AI cho các trợ lý lập trình AI

Tính năng •
Cài đặt •
Bắt đầu nhanh •
Best Practices •
Tài liệu •
Đóng góp

🇬🇧 English

---

🌟 Tại sao chọn Kim Quy?

Khi các trợ lý lập trình AI trở thành một phần không thể thiếu trong quy trình phát triển hiện đại, việc quản lý ngữ cảnh và hướng dẫn qua các dự án và công cụ khác nhau trở nên khó khăn. Kim Quy giải quyết vấn đề này bằng cách cung cấp:

- 🎯 Nguồn Chân lý Duy nhất: Định nghĩa hướng dẫn AI một lần, triển khai ở mọi nơi
- 🔄 Chuyển đổi Profile: Chuyển đổi tức thì giữa các ngữ cảnh công việc, cá nhân hoặc dự án cụ thể
- 🛠️ Hỗ trợ Đa công cụ: Hoạt động với Claude Code, Cursor và nhiều adapter sắp ra mắt
- 📝 Hệ thống Skill: Tổ chức hướng dẫn tái sử dụng trong các file SKILL.md với độ ưu tiên và gắn thẻ
- ⚡ TypeScript First: Hỗ trợ TypeScript đầy đủ với cấu hình type-safe

> Kim Quy (金龜) có nghĩa là "Rùa Vàng" trong tiếng Việt - một sinh vật huyền thoại tượng trưng cho trí tuệ và trường thọ.

✨ Tính năng

| Tính năng | Mô tả |
|-----------|-------|
| Quản lý Profile | Chuyển đổi giữa các ngữ cảnh AI khác nhau (công việc, cá nhân, dự án cụ thể) |
| Hệ thống Skill | Tổ chức hướng dẫn AI tái sử dụng trong các file SKILL.md |
| Hệ thống Adapter | Tạo cấu hình cho nhiều công cụ AI từ một nguồn duy nhất |
| Cấu hình TypeScript | Hỗ trợ TypeScript đầy đủ với kimquy.config.ts |
| Giao diện CLI | Giao diện dòng lệnh trực quan với chẩn đoán hữu ích |
| Xác thực | Xác thực tích hợp cho file skill và cấu hình |

📦 Cài đặt

$3

#### Sử dụng Bun (Khuyến nghị)

``bash
bun add -g kimquy
`

#### Sử dụng npm

`bash
npm install -g kimquy
`

#### Sử dụng pnpm

`bash
pnpm add -g kimquy
`

#### Từ mã nguồn

`bash
git clone https://github.com/nguyenphutrong/kimquy.git
cd kimquy
bun install
bun run build
bun link
`

$3

Copy prompt sau vào AI coding assistant:

`
Install and configure agentlens by following the instructions at:
https://github.com/nguyenphutrong/kimquy/blob/main/docs/ai-agent-setup.md
`

🚀 Bắt đầu nhanh

$3

Cấp project:

`bash
cd your-project
kq init --profile=default
`

Cấp user (global):

`bash
kq init --global --profile=default
`

Lệnh này tạo ra:
- kimquy.config.ts - File cấu hình
- .kimquy/ - Thư mục trạng thái
- skills/ - Thư mục skill mặc định với file SKILL.md mẫu

Global config nằm ở ~/.config/kimquy/ và được merge với config của project (project ưu tiên).

$3

Tạo file skills/typescript/SKILL.md:

`markdown
---
name: TypeScript Guidelines
tags: [typescript, coding]
profiles: [default]
priority: high
---

Hướng dẫn TypeScript

Khi nào sử dụng

- Khi viết code TypeScript
- Khi review các file TypeScript

Hướng dẫn

- Sử dụng strict mode
- Ưu tiên interfaces hơn type aliases cho object shapes
- Sử dụng const assertions cho literal types
`

$3

`bash
kq scan
`

$3

`bash
kq adapt claude-code
`

Lệnh này tạo ra .claude/skills.md và .claude/settings.local.json cho Claude Code.

$3

`bash
kq status
`

✅ Best Practices

- Dùng global config cho quy tắc chung, project config cho quy tắc riêng.
- Giữ skills ngắn gọn, tập trung và gắn tag để dễ tìm.
- Dùng profiles để tách ngữ cảnh work/personal.
- Dùng triggers cho các quy trình lặp lại.
- Sau khi sửa skills, chạy kq scan và kq adapt.

📖 Tài liệu

$3

| Lệnh | Mô tả |
|------|-------|
| kq init | Khởi tạo Kim Quy trong thư mục |
| kq use | Chuyển sang profile khác |
| kq profile | Quản lý profiles (list, show, create, delete) |
| kq scan | Quét và lập chỉ mục tất cả skills |
| kq skill | Quản lý skills (list, validate) |
| kq adapt | Tạo cấu hình cho công cụ AI |
| kq status | Hiển thị trạng thái cấu hình hiện tại |
| kq doctor | Chẩn đoán vấn đề cấu hình |
| kq import | Import skills từ công cụ bên ngoài |

📌 kq init

Khởi tạo Kim Quy trong thư mục hoặc global.

`bash
kq init [options]

Options:
--profile Tên profile ban đầu (mặc định: "default")
--force Ghi đè cấu hình hiện có
--global Khởi tạo cấu hình global ở cấp user
`

📌 kq use

Chuyển sang profile khác.

`bash
kq use work
kq use personal
`

📌 kq profile

Quản lý profiles.

`bash
kq profile list # Liệt kê tất cả profiles
kq profile show # Hiển thị chi tiết profile
kq profile create # Tạo profile mới
kq profile delete # Xóa profile
`

📌 kq scan

Quét và lập chỉ mục tất cả skills.

`bash
kq scan [options]

Options:
-d, --dir

Thư mục bổ sung để quét
-f, --force Bắt buộc quét lại toàn bộ
-v, --verbose Hiển thị output chi tiết
-q, --quiet Chỉ hiển thị tóm tắt
`

📌 kq skill

Quản lý skills.

`bash
kq skill list [options] # Liệt kê skills
-a, --all # Hiển thị tất cả skills
-t, --tags # Lọc theo tags
-v, --verbose # Hiển thị chi tiết

kq skill validate [options] # Xác thực các file SKILL.md
-v, --verbose # Hiển thị lỗi chi tiết
`

📌 kq adapt

Tạo cấu hình cho công cụ AI.

`bash
kq adapt [options]
kq adapt claude-code # Tạo cấu hình Claude Code
kq adapt cursor # Tạo cấu hình Cursor
kq adapt --all # Chạy tất cả adapters
kq adapt --dry-run # Xem trước thay đổi
kq adapt --clean # Xóa các file đã tạo
`

📌 kq import

Import skills từ công cụ bên ngoài.

`bash
kq import claude # Import Claude Code commands
kq import cursor # Import Cursor rules
kq import claude --output ./skills/claude
kq import cursor --force
`

$3

#### kimquy.config.ts

`typescript
export default {
profiles: {
default: {
name: 'Default Profile',
description: 'Ngữ cảnh AI mặc định',
skillDirs: ['./skills'],
envVars: {
PAI_PROFILE: 'default',
},
},
work: {
name: 'Work Profile',
description: 'Phát triển doanh nghiệp',
skillDirs: ['./skills/work', './skills/shared'],
},
},
defaultProfile: 'default',
skillPatterns: ['**/SKILL.md'],
};
`

#### Tùy chọn Profile

| Tùy chọn | Kiểu | Mô tả |
|----------|------|-------|
| name | string | Tên hiển thị của profile |
| description | string | Mô tả profile |
| skillDirs | string[] | Các thư mục để quét skills |
| envVars | object | Biến môi trường cần thiết lập |

$3

Skills là các file Markdown với YAML frontmatter:

`markdown
---
name: Tên Skill
description: Mô tả ngắn gọn
tags: [tag1, tag2]
profiles: [default, work]
priority: high
triggers: [/my-command]
---

Nội dung Skill

Nội dung Markdown sẽ được cung cấp cho AI.
`

#### Các trường Frontmatter

| Trường | Kiểu | Bắt buộc | Mặc định | Mô tả |
|--------|------|----------|----------|-------|
| name | string | ✅ | - | Tên skill |
| description | string | ❌ | "" | Mô tả ngắn gọn |
| tags | string[] | ❌ | [] | Tags để lọc |
| profiles | string[] | ❌ | [""] | Profiles skill này áp dụng ( = tất cả) |
| priority | low\|medium\|high | ❌ | medium | Độ ưu tiên skill |
| triggers | string[] | ❌ | - | Slash commands kích hoạt skill này |

$3

#### Claude Code

Tạo cấu hình cho Claude Code.

Các file được tạo:
- .claude/skills.md - Nội dung skill kết hợp
- .claude/settings.local.json - Cài đặt local
- .claude/commands/.md - Slash commands (nếu triggers được định nghĩa)

#### Cursor

Tạo cấu hình cho Cursor IDE.

Các file được tạo:
- .cursor/rules - File rules Cursor với nội dung skill

$3

`
your-project/
├── kimquy.config.ts # Cấu hình
├── .kimquy/
│ ├── state.json # Trạng thái hiện tại
│ └── skills.json # Cache skills
├── skills/
│ ├── typescript/
│ │ └── SKILL.md
│ └── react/
│ └── SKILL.md
└── .claude/ # Được tạo bởi adapter
├── skills.md
└── settings.local.json
`

🔧 Xử lý sự cố

"Kim Quy is not initialized"

Chạy kq init trong thư mục dự án của bạn.

"No skills found"

1. Kiểm tra skillDirs trong kimquy.config.ts
2. Chạy kq scan để khám phá skills
3. Đảm bảo các file skill có tên SKILL.md

"Invalid frontmatter"

Chạy kq skill validate --verbose để xem lỗi chi tiết.

Vấn đề cấu hình

Chạy kq doctor để chẩn đoán vấn đề.

🗺️ Lộ trình

- [ ] Windsurf Adapter - Hỗ trợ Windsurf IDE
- [ ] Zed Adapter - Hỗ trợ Zed editor
- [ ] VS Code Adapter - Hỗ trợ VS Code với các extension AI
- [ ] Skill Marketplace - Chia sẻ và khám phá skills cộng đồng
- [ ] Team Profiles - Profiles chia sẻ cho team
- [ ] Skill Inheritance - Kế thừa skills từ template cơ sở
- [ ] Watch Mode - Tự động tạo lại khi skill thay đổi

🤝 Đóng góp

Chúng tôi hoan nghênh đóng góp! Vui lòng đọc Hướng dẫn Đóng góp trước khi gửi PR.

1. Fork repository
2. Tạo nhánh tính năng (git checkout -b feature/amazing-feature)
3. Commit thay đổi (git commit -m 'feat: add amazing feature')
4. Push lên nhánh (git push origin feature/amazing-feature`)
5. Mở Pull Request

Xem issues đang mở để biết danh sách tính năng đề xuất và vấn đề đã biết.

📄 Giấy phép

Dự án này được cấp phép theo MIT License - xem file LICENSE để biết chi tiết.

🙏 Lời cảm ơn

- Lấy cảm hứng từ nhu cầu quản lý ngữ cảnh AI tốt hơn
- Được xây dựng với Bun, Commander.js, và Zod
- Cảm ơn tất cả contributors

---

Made with ❤️ by Trong Nguyen