NeboAI
NeboAI
Bắt đầu

Tham chiếu SKILL.md

Trang này liệt kê mọi phần của một kỹ năng mà Nebo đọc: các trường frontmatter, các biến được mở rộng, các công cụ nhân viên dùng để làm việc với kỹ năng và môi trường chạy script.

Đị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ườngKiểuMặc địnhÝ nghĩa
namestringbắt buộcMã đị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.
descriptionstringbắt buộcKỹ 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.
versionstring"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.
triggersdanh 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.
platformdanh sách chuỗitất cảmacos, linux, windows. Kỹ năng chỉ được nạp ở nơi có giá trị khớp.
capabilitiesdanh 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.
metadatamap{}Chứa secrets và allowed_domains. Xem bên dưới.
requiresdanh 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 "*".
pluginsdanh 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.
dependenciesdanh sách chuỗi[]Tên ngắn của các kỹ năng bắt buộc phải có.
priorityinteger0Sắ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.
authorstring""Được lưu để hiển thị.
licensestring""Được lưu để hiển thị.
compatibilitystring""Ghi chú tự do, tối đa 500 byte.
tagsdanh sách chuỗi[]Được lưu để hiển thị.
allowed-toolsstring""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
keyTên biến môi trường mà script nhận được. Bắt buộc.
labelTên hiển thị cho chủ sở hữu.
hintNơi lấy giá trị.
requiredKhi 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ếnGiá 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.
$ARGUMENTSCá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_skillname, argsNạ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_skillsqueryTrả 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_filename, 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_skillname, contentGhi 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_skillnameXóa một kỹ năng của người dùng.
install_skillcodeCài một kỹ năng từ chợ ứng dụng bằng mã cài đặt SKIL- của nó.
configure_skillname, 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_skillname, rating, reviewChấm điểm một kỹ năng trên chợ ứng dụng từ 1 đến 5.
read_skill_reviewsnameĐọc các bài đánh giá của một kỹ năng trên chợ ứng dụng.
executeskill, script, args, timeoutChạ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.

ScriptMôi trường chạy
.pyPython, qua uv đi kèm Nebo nếu có, nếu không thì python3.
.ts, .jsBun đi kèm Nebo nếu có, nếu không thì node.
bin/<file> hoặc binaryChạy trực tiếp.
.shKhô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ếnGiá trị
SKILL_ARGSĐối tượng args dưới dạng JSON.
Mỗi key của thông tin bí mậtGiá 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ực storage bổ 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 network cho phép truy cập các kho gói và các tên miền được liệt kê trong metadata.allowed_domains.

Tệp và giới hạn

MụcQuy tắc
Tài nguyênMọi tệp trừ SKILL.md, manifest.json, signatures.json và các tệp ẩn.
Tệp thực thiCác tệp trong scripts/ hoặc bin/, và một tệp ở thư mục gốc tên binary.
Đường dẫnTươ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ắtMột thư mục có SKILL.md.disabled thay vì SKILL.md.
Danh sách kỹ năngMỗ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.