Skills

Skills là các gói instruction tái sử dụng mà Bestie load vào chat system prompt. Dùng skill cho hành vi lặp lại, workflow, guardrails hoặc thói quen riêng của project mà Bestie nên nhớ qua nhiều cuộc trò chuyện.

Cứ hiểu skill là một prompt module nhỏ, có tên rõ ràng. Nếu một hành vi cần dùng lại nhiều lần, đừng paste đi paste lại trong chat như goblin thiếu ngủ. Cho nó vào skill.

Bestie hỗ trợ hai nguồn skill:

• skill local bạn tự tạo dưới ~/.bestie/skills/<skill-name>/SKILL.md
• skill từ remote library chính thức trên GitHub, được dùng trong Web UI skill library

Cấu trúc file

Mỗi skill nằm trong một folder riêng dưới runtime app directory của Bestie:

.bestie/skills/<skill-name>/SKILL.md

Ví dụ:

.bestie/
  skills/
    code-reviewer/
      SKILL.md
    release-helper/
      SKILL.md

Tên folder là skill identifier ổn định. Nên dùng chữ thường và mô tả rõ, ví dụ code-reviewer, docs-polisher hoặc incident-debugger.

Format SKILL.md

Skill là một file Markdown có YAML frontmatter, sau đó là phần instruction.

---
name: code-reviewer
description: Review code changes for bugs, regressions, missing tests, and risky behavior.
---

# Code Reviewer

Use this skill when the user asks for a code review, PR review, or risk assessment.

## Behavior

- Prioritize bugs, security issues, behavioral regressions, and missing tests.
- Put findings first, ordered by severity.
- Include file and line references when available.
- Keep summaries short unless the user asks for detail.

Frontmatter fields

Field	Bắt buộc	Mục đích
name	Có	Tên skill để người dùng đọc được. Thường trùng với tên folder.
description	Có	Mô tả trigger ngắn, cho Bestie biết khi nào skill liên quan.

Hãy viết description cụ thể. Giúp làm linh tinh không phải mô tả; nó là tiếng kêu cứu mặc áo măng tô.

Cách Bestie load skills

Bestie load skills từ runtime app directory khi khởi động hoặc khi init chat, tùy command path.

Các điểm cần nhớ:

• Chỉ load file .bestie/skills/<skill-name>/SKILL.md.
• File SKILL.md rỗng sẽ bị bỏ qua.
• Nội dung skill được trim trước khi inject.
• Skills được load theo thứ tự tên folder để prompt ổn định.
• Loader dừng khi combined skills prompt chạm byte budget.

Vì skills dùng chung prompt budget, hãy giữ skill gọn và tập trung. Một skill nên dạy một hành vi bền vững, không phải biến thành bãi rác cho mọi ý nghĩ từng lóe lên trong đầu.

Khi nào nên tạo skill

Tạo skill khi muốn Bestie nhất quán theo một workflow, ví dụ:

• style review code
• checklist release
• quy tắc viết docs
• các bước debug incident
• convention riêng của project
• quy trình research hoặc planning lặp lại

Đừng tạo skill cho context dùng một lần. Nếu instruction chỉ cần cho task hiện tại, nói thẳng trong chat là đủ.

Lệnh liên quan

List skills đã cài:

bestie skills
bestie skills list

Cả hai lệnh đều hiển thị skills Bestie discover được từ runtime skills directory.

Remote skill library

Web UI skill library dùng official remote registry mặc định:

https://raw.githubusercontent.com/sirquy/bestie-skills/master/registry.json

Bestie verify registry bằng sidecar checksum tại:

https://raw.githubusercontent.com/sirquy/bestie-skills/master/registry.sha256

Registry metadata được cache tại:

~/.bestie/data/skill-remote-registry-cache.json

Remote install được gate rất rõ:

• registry URL phải dùng https://
• registry phải validate và verify bằng checksum hoặc detached signature
• installPolicy phải là ask
• owner phải confirm rõ ràng khi install, update, rollback, enable/disable hoặc uninstall qua UI/API flow

Khi Bestie cài một library skill, nó ghi nội dung skill và metadata nguồn không chứa secret:

~/.bestie/skills/<skill-name>/SKILL.md
~/.bestie/skills/<skill-name>/bestie-skill.json

Manifest ghi source, version, checksum, declared permissions và trạng thái enabled. Skill bị disable vẫn hiện trong Web UI nhưng không được inject vào prompt ở các lần chat sau.

Workflow trong library

Dùng Web UI skill library để:

• preview remote skill trước khi cài
• xem diff trước khi update skill đã cài
• install hoặc update sau khi confirm rõ ràng
• rollback về bản đã cài trước đó khi có
• enable hoặc disable skill mà không xóa
• uninstall skill; file bị xóa được archive dưới .bestie/skills/.uninstalled/

Editor chỉ dành cho installed skills. Remote library preview là read-only cho tới khi bạn cài skill.

Best practices

• Mỗi skill nên có mục đích hẹp.
• Viết trigger rõ trong description.
• Giữ instruction ngắn và hành động được.
• Ưu tiên checklist thay vì bài văn dài.
• Không bao giờ lưu secrets, API keys, tokens hoặc private config trong skills.
• Xem remote skill text là instruction không đáng tin cho tới khi bạn review nội dung.
• Tránh các skill mâu thuẫn nhau.
• Đưa rule riêng của project vào project skill, đừng nhét lặp lại vào từng chat prompt.

Troubleshooting

Nếu skill không hiện ra:

• Kiểm tra file có tên chính xác là SKILL.md.
• Kiểm tra file nằm đúng dưới .bestie/skills/<skill-name>/.
• Kiểm tra file không rỗng.
• Chạy bestie skills list để verify discovery.
• Rút gọn skill quá lớn nếu các skill phía sau bị thiếu do chạm byte budget.
• Trong Web UI, kiểm tra skill có bị disable trong bestie-skill.json không.
• Với lỗi remote library, refresh hoặc clear registry cache và kiểm tra trạng thái checksum verification.