Sử dụng script trong skill

Cách chạy lệnh và đóng gói các script thực thi trong skill của bạn.

Skill có thể hướng dẫn các agent chạy những lệnh shell và đóng gói các script có thể tái sử dụng trong thư mục scripts/. Hướng dẫn này bao gồm các lệnh một lần, các script độc lập với những dependency riêng và cách thiết kế giao diện script để sử dụng cho agent.

Lệnh một lần

Khi một gói hiện có đã thực hiện những gì bạn cần, bạn có thể tham chiếu trực tiếp nó trong hướng dẫn SKILL.md của mình mà không cần thư mục scripts/. Nhiều hệ sinh thái cung cấp các công cụ tự động giải quyết những dependency trong runtime.

uvx chạy các gói Python trong môi trường biệt lập với khả năng lưu cache mạnh mẽ. Nó được tích hợp sẵn trong uv.

uvx ruff@0.8.0 check .
uvx black@24.10.0 .

• Không được tích hợp sẵn trong Python - yêu cầu cài đặt riêng.

• Nhanh. Cache mạnh mẽ nên các lần chạy lặp lại gần như tức thì.

Mẹo cho các lệnh dùng một lần trong skill:

• Ghim phiên bản (ví dụ: npx eslint@9.0.0) để lệnh hoạt động nhất quán theo thời gian.

• Nêu rõ các điều kiện tiên quyết trong SKILL.md của bạn (ví dụ: “Yêu cầu Node.js 18+”) thay vì giả định môi trường của agent đã có chúng. Đối với các yêu cầu ở cấp độ runtime, hãy sử dụng trường tương thích ở đầu thông tin.

• Chuyển những lệnh phức tạp vào các script. Lệnh dùng một lần hoạt động tốt khi bạn gọi một công cụ với một vài flag. Khi một lệnh trở nên đủ phức tạp đến mức khó thực hiện đúng ngay lần đầu, một script đã được kiểm thử trong scripts/ sẽ đáng tin cậy hơn.

Tham chiếu các script từ SKILL.md

Sử dụng đường dẫn tương đối từ thư mục gốc của skill để tham chiếu các file được đóng gói. Agent sẽ tự động giải quyết các đường dẫn này - không cần đường dẫn tuyệt đối.

Liệt kê các script có sẵn trong SKILL.md của bạn để agent biết chúng tồn tại:

## Available scripts

- **`scripts/validate.sh`** — Validates configuration files
- **`scripts/process.py`** — Processes input data

Sau đó, hướng dẫn agent chạy chúng:

## Workflow

1. Run the validation script:
   ```bash
   bash scripts/validate.sh "$INPUT_FILE"
   ```

2. Process the results:
   ```bash
   python3 scripts/process.py --input results.json
   ```

Quy ước đường dẫn tương đối tương tự cũng hoạt động trong các file hỗ trợ như references/*.md - đường dẫn thực thi script (trong các block code) là tương đối so với thư mục gốc của skill, vì agent chạy các lệnh từ đó.

Các script độc lập

Khi bạn cần logic có thể tái sử dụng, hãy đóng gói một script trong scripts/ và khai báo những dependency của chính nó trực tiếp. Agent có thể chạy script bằng một lệnh duy nhất - không cần file kê khai riêng biệt hoặc bước cài đặt.

Một số ngôn ngữ hỗ trợ khai báo dependency trực tiếp:

PEP 723 định nghĩa một định dạng chuẩn cho siêu dữ liệu script trực tiếp. Khai báo những dependency trong một khối TOML bên trong dấu # ///:

# /// script
# dependencies = [
#   "beautifulsoup4",
# ]
# ///

from bs4 import BeautifulSoup

html = '<html><body><h1>Welcome</h1><p class="info">This is a test.</p></body></html>'
print(BeautifulSoup(html, "html.parser").select_one("p.info").get_text())

Chạy với UV (khuyến nghị):

uv run scripts/extract.py

Lệnh uv run tạo một môi trường biệt lập, cài đặt những dependency đã khai báo và chạy script. pipx (`pipx run scripts/extract.py`) cũng hỗ trợ PEP 723.

• Gắn phiên bản với trình chỉ định PEP 508: "beautifulsoup4>=4.12,<5".

• Sử dụng `requires-python` để giới hạn phiên bản Python.

• Sử dụng `uv lock --script` để tạo lockfile nhằm đảm bảo khả năng tái tạo đầy đủ.

Thiết kế script để sử dụng với agent

Khi một agent chạy script của bạn, nó sẽ đọc `stdout` và `stderr` để quyết định hành động tiếp theo. Một vài lựa chọn thiết kế giúp các agent dễ dàng sử dụng script hơn đáng kể.

Tránh các prompt tương tác

Đây là một yêu cầu bắt buộc của môi trường thực thi agent. Các agent hoạt động trong những shell không tương tác - chúng không thể phản hồi các prompt TTY, hộp thoại mật khẩu hoặc menu xác nhận. Một script bị chặn bởi đầu vào tương tác sẽ bị treo vô thời hạn.

Chấp nhận tất cả đầu vào thông qua flag dòng lệnh, biến môi trường hoặc `stdin`:

# Bad: hangs waiting for input
$ python scripts/deploy.py
Target environment: _

# Good: clear error with guidance
$ python scripts/deploy.py
Error: --env is required. Options: development, staging, production.
Usage: python scripts/deploy.py --env staging --tag v1.2.3

Hướng dẫn sử dụng bằng lệnh --help

--help là cách chính để agent hiểu giao diện của script. Bao gồm mô tả ngắn gọn, các flag có sẵn và ví dụ sử dụng:

Usage: scripts/process.py [OPTIONS] INPUT_FILE

Process input data and produce a summary report.

Options:
  --format FORMAT    Output format: json, csv, table (default: json)
  --output FILE      Write output to FILE instead of stdout
  --verbose          Print progress to stderr

Examples:
  scripts/process.py data.csv
  scripts/process.py --format csv --output report.csv data.csv

Hãy viết ngắn gọn - kết quả đầu ra sẽ hiển thị trong cửa sổ ngữ cảnh của agent cùng với tất cả những thứ khác mà nó đang xử lý.

Viết các thông báo lỗi hữu ích

Khi agent gặp lỗi, thông báo sẽ trực tiếp định hình nỗ lực tiếp theo của nó. Một thông báo khó hiểu như “Error: invalid input” sẽ lãng phí một lượt xử lý. Thay vào đó, hãy cho biết điều gì đã xảy ra sai, điều gì được mong đợi và điều cần thử:

Error: --format must be one of: json, csv, table.
       Received: "xml"

Sử dụng định dạng đầu ra có cấu trúc

Ưu tiên các định dạng có cấu trúc - JSON, CSV, TSV - thay vì văn bản tùy ý. Các định dạng có cấu trúc có thể được sử dụng bởi cả agent và những công cụ tiêu chuẩn (jq, cut, awk), giúp script của bạn có thể được kết hợp trong các quy trình xử lý dữ liệu.

# Whitespace-aligned — hard to parse programmatically
NAME          STATUS    CREATED
my-service    running   2025-01-15

# Delimited — unambiguous field boundaries
{"name": "my-service", "status": "running", "created": "2025-01-15"}

Tách dữ liệu khỏi thông tin chẩn đoán: Gửi dữ liệu có cấu trúc tới stdout và các thông báo tiến trình, cảnh báo và những thông tin chẩn đoán khác tới stderr. Điều này cho phép agent thu thập đầu ra sạch, có thể phân tích được trong khi vẫn có quyền truy cập vào thông tin chẩn đoán khi cần.

Những cân nhắc khác

• Tính bất biến. Agent có thể thử lại các lệnh. "Tạo nếu chưa tồn tại" an toàn hơn "tạo và báo lỗi khi trùng lặp".

• Ràng buộc đầu vào. Từ chối đầu vào không rõ ràng với lỗi rõ ràng thay vì đoán mò. Sử dụng kiểu liệt kê và tập hợp đóng khi có thể.

• Hỗ trợ chạy thử. Đối với các thao tác phá hủy hoặc có trạng thái, flag --dry-run cho phép agent xem trước những gì sẽ xảy ra.

• Exit code có ý nghĩa. Sử dụng các exit code riêng biệt cho những loại lỗi khác nhau (không tìm thấy, đối số không hợp lệ, lỗi xác thực) và ghi lại chúng trong đầu ra --help của bạn để agent biết ý nghĩa của từng code.

• Các giá trị mặc định an toàn. Cân nhắc xem các thao tác phá hủy có nên yêu cầu flag xác nhận rõ ràng (--confirm, --force) hoặc những biện pháp bảo vệ khác phù hợp với mức độ rủi ro hay không.

• Kích thước đầu ra có thể dự đoán được. Nhiều công cụ giám sát tự động cắt bớt đầu ra của công cụ khi vượt quá một ngưỡng nhất định (ví dụ: 10 - 30 nghìn ký tự), có thể dẫn đến mất thông tin quan trọng. Nếu script của bạn có thể tạo ra đầu ra lớn, hãy mặc định là tóm tắt hoặc một giới hạn hợp lý, và hỗ trợ các flag như --offset để agent có thể yêu cầu thêm thông tin khi cần. Hoặc, nếu đầu ra lớn và không thể phân trang, hãy yêu cầu các agent truyền flag --output chỉ định file đầu ra hoặc - để chọn rõ ràng sử dụng stdout.