Định dạng tệp
SKILL.md là văn bản UTF-8. Tệp bắt đầu bằng một dòng gồm ba dấu gạch nối, tiếp theo là frontmatter YAML, rồi một dòng đóng gồm ba dấu gạch nối. Mọi thứ sau đó là phần thân: các chỉ dẫn Markdown mà nhân viên nhận được khi nạp kỹ năng. Nebo tìm tệp theo tên, không phân biệt chữ hoa chữ thường.
---
name: expense-review
description: Check submitted expenses against the company policy and flag anything that needs a receipt or an approval. Use when someone asks to review expenses or a reimbursement request.
version: "1.2.0"
author: Example Co
license: MIT
tags: [finance, expenses]
triggers: [reimbursement, expense report]
platform: [macos, linux, windows]
capabilities: [network]
metadata:
allowed_domains: [api.example.com]
secrets:
- key: EXAMPLE_API_KEY
label: Example API key
hint: Create one at https://example.com/settings/keys
required: true
requires:
- name: receipt-capture
version: ">=1.0.0"
plugins:
- name: example-ledger
version: ">=2.0.0"
optional: true
---
# Expense review
Follow the policy in references/policy.md ... Các trường frontmatter
Chỉ name và description là bắt buộc. Một trường sai kiểu sẽ làm hỏng toàn bộ tệp, nên kỹ năng sẽ không được nạp. Các khóa không được liệt kê ở đây sẽ bị bỏ qua.
| Trường | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
name | string | bắt buộc | Mã định danh. [a-z0-9-], không có dấu gạch nối ở đầu, ở cuối hoặc hai dấu liền nhau, tối đa 64 byte. Trùng với tên thư mục. |
description | string | bắt buộc | Kỹ năng làm gì và khi nào nên dùng. Tối đa 1.024 byte. Hiển thị trong danh sách kỹ năng của nhân viên và được find_skills chấm điểm. |
version | string | "1.0.0" | Phiên bản ngữ nghĩa. Được kiểm tra bởi các khoảng requires của kỹ năng khác. Hãy đặt trong dấu ngoặc kép. |
triggers | danh sách chuỗi | [] | Các từ và cụm từ mô tả khi nào kỹ năng được áp dụng. Tối đa ba mục xuất hiện trong danh sách kỹ năng; tất cả đều được tính trong find_skills. Chúng không bao giờ tự nạp một kỹ năng. |
platform | danh sách chuỗi | tất cả | macos, linux, windows. Kỹ năng chỉ được nạp ở nơi có giá trị khớp. |
capabilities | danh sách chuỗi | [] | network và storage mở rộng hộp cát chạy script. Xem phần Hộp cát chạy script. |
metadata | map | {} | Chứa secrets và allowed_domains. Xem bên dưới. |
requires | danh sách {name, version} | [] | Các kỹ năng khác mà kỹ năng này dựa vào. name là tên ngắn của kỹ năng; version là một khoảng semver, mặc định "*". |
plugins | danh sách {name, version, optional} | [] | Các plugin mà kỹ năng này dùng. version mặc định là "*", optional mặc định là false. |
dependencies | danh sách chuỗi | [] | Tên ngắn của các kỹ năng bắt buộc phải có. |
priority | integer | 0 | Sắp xếp kỹ năng trong danh sách quản lý. Không ảnh hưởng tới việc nhân viên chọn kỹ năng nào. |
author | string | "" | Được lưu để hiển thị. |
license | string | "" | Được lưu để hiển thị. |
compatibility | string | "" | Ghi chú tự do, tối đa 500 byte. |
tags | danh sách chuỗi | [] | Được lưu để hiển thị. |
allowed-tools | string | "" | Một chuỗi phân tách bằng dấu cách. Được lưu lại; không được thực thi. |
Khi một kỹ năng được nêu trong requires hoặc dependencies bị thiếu hoặc nằm ngoài khoảng phiên bản, hoặc một plugin bắt buộc chưa được cài, kỹ năng vẫn được nạp và bị đánh dấu là suy giảm. Chủ sở hữu sẽ thấy còn thiếu gì.
Thông tin bí mật
Khai báo thông tin đăng nhập mà các script của kỹ năng cần trong metadata.secrets. Chủ sở hữu cung cấp giá trị, và Nebo lưu chúng ở dạng mã hóa cho kỹ năng đó.
metadata:
secrets:
- key: EXAMPLE_API_KEY
label: Example API key
hint: Create one at https://example.com/settings/keys
required: true | Khóa | Ý nghĩa |
|---|---|
key | Tên biến môi trường mà script nhận được. Bắt buộc. |
label | Tên hiển thị cho chủ sở hữu. |
hint | Nơi lấy giá trị. |
required | Khi là true, execute từ chối chạy các script của kỹ năng cho đến khi giá trị được đặt. Mặc định false. |
Nhân viên đặt giá trị bằng configure_skill. Bạn có thể tham chiếu một bí mật trong phần thân dưới dạng ${secret.KEY}, tuy vậy script nên đọc biến môi trường thay vì cách này.
Biến mẫu
Nebo thay thế các biến này trong phần thân khi nhân viên nạp kỹ năng. Chúng không được thay thế bên trong các tệp khác; script đọc biến môi trường thay vào đó.
| Biến | Giá trị |
|---|---|
${NEBO_SKILL_DIR} | Đường dẫn tuyệt đối tới thư mục của kỹ năng. |
${NEBO_DATA_DIR} | Một thư mục có thể ghi dành cho kỹ năng này: <data>/appdata/skills/<name>. Được tạo ở lần dùng đầu tiên. |
${NEBO_USER_NAME} | Tên của chủ sở hữu. |
${NEBO_OS} | Hệ điều hành. |
${NEBO_ARCH} | Kiến trúc bộ xử lý. |
${plugin.SLUG_BIN} | Đường dẫn tới tệp nhị phân của một plugin đã khai báo. Slug được viết hoa, dấu gạch nối thành dấu gạch dưới: example-ledger trở thành ${plugin.EXAMPLE_LEDGER_BIN}. |
${secret.KEY} | Giá trị của một thông tin bí mật đã khai báo. |
$ARGUMENTS | Các args được truyền cho use_skill. Khi phần thân không có $ARGUMENTS, các đối số được nối vào sau phần thân. |
Công cụ kỹ năng
Nhân viên làm việc với kỹ năng thông qua các công cụ này. use_skill luôn có sẵn; các công cụ khác được nạp khi nhân viên cần.
| Công cụ | Tham số | Chức năng |
|---|---|---|
use_skill | name, args | Nạp một kỹ năng. Trả về phần thân đã mở rộng, đường dẫn thư mục và 20 tên tệp đầu tiên. Bật lại kỹ năng đã bị tắt. |
find_skills | query | Trả về tối đa 10 kỹ năng được xếp hạng theo mức khớp tên, trình kích hoạt và mô tả. |
read_skill_file | name, path | Đọc một tệp trong thư mục của kỹ năng. Nếu không có path, liệt kê các tệp và kích thước của chúng. |
save_skill | name, content | Ghi một SKILL.md hoàn chỉnh vào thư mục kỹ năng của người dùng. Không thể ghi đè kỹ năng từ chợ ứng dụng. |
delete_skill | name | Xóa một kỹ năng của người dùng. |
install_skill | code | Cài một kỹ năng từ chợ ứng dụng bằng mã cài đặt SKIL- của nó. |
configure_skill | name, key, value | Đặt một thông tin bí mật. Nếu không có key, hiển thị những gì kỹ năng cần. |
rate_skill | name, rating, review | Chấm điểm một kỹ năng trên chợ ứng dụng từ 1 đến 5. |
read_skill_reviews | name | Đọc các bài đánh giá của một kỹ năng trên chợ ứng dụng. |
execute | skill, script, args, timeout | Chạy một script từ thư mục của kỹ năng. Xem phần Hộp cát chạy script. |
Hộp cát chạy script
Công cụ execute chạy một script từ thư mục của kỹ năng. Nó chọn môi trường chạy dựa trên tệp.
| Script | Môi trường chạy |
|---|---|
.py | Python, qua uv đi kèm Nebo nếu có, nếu không thì python3. |
.ts, .js | Bun đi kèm Nebo nếu có, nếu không thì node. |
bin/<file> hoặc binary | Chạy trực tiếp. |
.sh | Không được hỗ trợ. |
Mỗi lần chạy bắt đầu với một môi trường trống cùng các biến sau:
| Biến | Giá trị |
|---|---|
SKILL_ARGS | Đối tượng args dưới dạng JSON. |
Mỗi key của thông tin bí mật | Giá trị bí mật đã được giải mã. |
<PLUGIN>_BIN | Đường dẫn tới tệp nhị phân của từng plugin đã khai báo. Các thư mục plugin cũng được thêm vào PATH. |
import json, os
args = json.loads(os.environ.get("SKILL_ARGS", "{}"))
api_key = os.environ["EXAMPLE_API_KEY"]
print(json.dumps({"checked": len(args.get("items", []))})) Script chạy trong một bản sao tạm thời của thư mục kỹ năng, với thời gian chờ mặc định là 30 giây. Trên macOS và Linux, script chạy trong hộp cát của hệ điều hành:
- Script không thể đọc kho thông tin đăng nhập, dữ liệu trình duyệt và chuỗi khóa, hay cài đặt và cơ sở dữ liệu riêng của Nebo.
- Script chỉ có thể ghi vào thư mục làm việc của nó và
/tmp/nebo. Năng lựcstoragebổ sung thư mục dữ liệu của Nebo. - Script không có quyền truy cập mạng. Năng lực
networkcho phép truy cập các kho gói và các tên miền được liệt kê trongmetadata.allowed_domains.
Tệp và giới hạn
| Mục | Quy tắc |
|---|---|
| Tài nguyên | Mọi tệp trừ SKILL.md, manifest.json, signatures.json và các tệp ẩn. |
| Tệp thực thi | Các tệp trong scripts/ hoặc bin/, và một tệp ở thư mục gốc tên binary. |
| Đường dẫn | Tương đối so với thư mục kỹ năng. Đường dẫn có .. hoặc thoát ra ngoài thư mục sẽ bị từ chối. |
| Kỹ năng bị tắt | Một thư mục có SKILL.md.disabled thay vì SKILL.md. |
| Danh sách kỹ năng | Mỗi mục bị cắt ở 250 ký tự. Khi toàn bộ danh sách vượt quá 8.000 ký tự, các kỹ năng dùng chung được rút gọn trước; kỹ năng riêng của nhân viên giữ nguyên mục đầy đủ. |
Giới hạn cho các tệp bạn phát hành lên chợ ứng dụng nằm trên trang Phát hành.