Chuyển tới nội dung chính

Creating Skills

#Tạo kỹ năng

Kỹ năng là cách ưa thích để bổ sung các khả năng mới cho Đặc vụ Hermes. Chúng dễ tạo hơn các công cụ, không yêu cầu thay đổi mã đối với tác nhân và có thể chia sẻ với cộng đồng.

Đó nên là Kỹ năng hay Công cụ?​

Hãy biến nó thành Kỹ năng khi:

  • Khả năng có thể được thể hiện dưới dạng hướng dẫn + lệnh shell + công cụ hiện có
  • Nó bao bọc một CLI hoặc API bên ngoài mà tác nhân có thể gọi thông qua terminal hoặc web_extract
  • Không cần tích hợp Python tùy chỉnh hoặc quản lý khóa API được đưa vào tác nhân
  • Ví dụ: tìm kiếm arXiv, quy trình làm việc git, quản lý Docker, xử lý PDF, gửi email qua công cụ CLI

Biến nó thành Công cụ khi:

  • Nó yêu cầu tích hợp từ đầu đến cuối với khóa API, luồng xác thực hoặc cấu hình nhiều thành phần
  • Nó cần logic xử lý tùy chỉnh phải thực thi chính xác mọi lúc
  • Nó xử lý dữ liệu nhị phân, phát trực tuyến hoặc các sự kiện thời gian thực
  • Ví dụ: tự động hóa trình duyệt, TTS, phân tích tầm nhìn

Cấu trúc thư mục kỹ năng​

Các kỹ năng được tập hợp nằm trong skills/ được sắp xếp theo danh mục. Các kỹ năng tùy chọn chính thức sử dụng cấu trúc tương tự trong các kỹ năng tùy chọn/:

skills/
├── research/
│   └── arxiv/
│       ├── SKILL.md              # Required: main instructions
│       └── scripts/              # Optional: helper scripts
│           └── search_arxiv.py
├── productivity/
│   └── ocr-and-documents/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
└── ...

Định dạng SKILL.md​

---
name: my-skill
description: Brief description (shown in skill search results)
version: 1.0.0
author: Your Name
license: MIT
platforms: [macos, linux]          # Optional — restrict to specific OS platforms
                                   #   Valid: macos, linux, windows
                                   #   Omit to load on all platforms (default)
metadata:
  hermes:
    tags: [Category, Subcategory, Keywords]
    related_skills: [other-skill-name]
    requires_toolsets: [web]            # Optional — only show when these toolsets are active
    requires_tools: [web_search]        # Optional — only show when these tools are available
    fallback_for_toolsets: [browser]    # Optional — hide when these toolsets are active
    fallback_for_tools: [browser_navigate]  # Optional — hide when these tools exist
    config:                              # Optional — config.yaml settings the skill needs
      - key: my.setting
        description: "What this setting controls"
        default: "sensible-default"
        prompt: "Display prompt for setup"
required_environment_variables:          # Optional — env vars the skill needs
  - name: MY_API_KEY
    prompt: "Enter your API key"
    help: "Get one at https://example.com"
    required_for: "API access"
---

# Skill Title

Brief intro.

## When to Use
Trigger conditions — when should the agent load this skill?

## Quick Reference
Table of common commands or API calls.

## Procedure
Step-by-step instructions the agent follows.

## Pitfalls
Known failure modes and how to handle them.

## Verification
How the agent confirms it worked.

Kỹ năng dành riêng cho nền tảng​

Các kỹ năng có thể tự giới hạn ở các hệ điều hành cụ thể bằng cách sử dụng trường nền tảng:

platforms: [macos]            # macOS only (e.g., iMessage, Apple Reminders)
platforms: [macos, linux]     # macOS and Linux
platforms: [windows]          # Windows only

Khi được đặt, kỹ năng sẽ tự động bị ẩn khỏi lời nhắc hệ thống, skills_list() và các lệnh gạch chéo trên các nền tảng không tương thích. Nếu bị bỏ qua hoặc để trống, kỹ năng sẽ tải trên tất cả các nền tảng (tương thích ngược).

Kích hoạt kỹ năng có điều kiện​

Kỹ năng có thể khai báo sự phụ thuộc vào các công cụ hoặc bộ công cụ cụ thể. Điều này kiểm soát xem kỹ năng có xuất hiện trong lời nhắc hệ thống trong một phiên nhất định hay không.

metadata:
  hermes:
    requires_toolsets: [web]           # Hide if the web toolset is NOT active
    requires_tools: [web_search]       # Hide if web_search tool is NOT available
    fallback_for_toolsets: [browser]   # Hide if the browser toolset IS active
    fallback_for_tools: [browser_navigate]  # Hide if browser_navigate IS available
Lĩnh vựcHành vi
requires_toolsetsKỹ năng bị ẩn khi BẤT KỲ bộ công cụ nào được liệt kê không có sẵn
requires_toolsKỹ năng bị ẩn khi BẤT KỲ công cụ nào được liệt kê không có sẵn
dự phòng_for_toolsetsKỹ năng bị ẩn khi BẤT KỲ bộ công cụ nào được liệt kê **có sẵn
dự phòng_for_toolsKỹ năng bị ẩn khi BẤT KỲ công cụ nào được liệt kê **có sẵn

Trường hợp sử dụng cho fallback_for_*: Tạo một kỹ năng dùng như một giải pháp thay thế khi không có công cụ chính. Ví dụ: kỹ năng duckduckgo-search với fallback_for_tools: [web_search] chỉ hiển thị khi công cụ tìm kiếm trên web (yêu cầu khóa API) không được định cấu hình.

Trường hợp sử dụng cho requires_*: Tạo một kỹ năng chỉ có ý nghĩa khi có một số công cụ nhất định. Ví dụ: kỹ năng xử lý quy trình quét web với requires_toolsets: [web] sẽ không làm lộn xộn lời nhắc khi các công cụ web bị tắt.

Yêu cầu về biến môi trường​

Kỹ năng có thể khai báo các biến môi trường mà họ cần. Khi một kỹ năng được tải thông qua skill_view, các biến bắt buộc của nó sẽ tự động được đăng ký để chuyển sang môi trường thực thi hộp cát (terminal, exec_code).

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: "Tenor API key"               # Shown when prompting user
    help: "Get your key at https://tenor.com"  # Help text or URL
    required_for: "GIF search functionality"   # What needs this var

Mỗi mục hỗ trợ:

  • name (bắt buộc) — tên biến môi trường
  • prompt (tùy chọn) — văn bản nhắc nhở khi hỏi người dùng về giá trị
  • help (tùy chọn) — văn bản trợ giúp hoặc URL để lấy giá trị
  • required_for (tùy chọn) — mô tả tính năng nào cần biến này

Người dùng cũng có thể định cấu hình các biến chuyển qua theo cách thủ công trong config.yaml:

terminal:
  env_passthrough:
    - MY_CUSTOM_VAR
    - ANOTHER_VAR

Xem skills/apple/ để biết ví dụ về các kỹ năng chỉ dành cho macOS.

Thiết lập an toàn khi tải​

Sử dụng required_environment_variables khi một kỹ năng cần khóa API hoặc mã thông báo. Các giá trị bị thiếu không ẩn kỹ năng khỏi bị phát hiện. Thay vào đó, Hermes nhắc nhở họ một cách an toàn khi kỹ năng được tải trong CLI cục bộ.

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: Get a key from https://developers.google.com/tenor
    required_for: full functionality

Người dùng có thể bỏ qua quá trình thiết lập và tiếp tục tải kỹ năng. Hermes không bao giờ tiết lộ giá trị bí mật thô cho người mẫu. Các phiên cổng và nhắn tin hiển thị hướng dẫn thiết lập cục bộ thay vì thu thập bí mật trong băng tần.

Sandbox Passthrough

Khi kỹ năng của bạn được tải, mọi required_environment_variables đã được đặt sẽ tự động được chuyển qua tới các hộp cát execute_code và terminal — bao gồm cả các chương trình phụ trợ từ xa như Docker và Modal. Tập lệnh kỹ năng của bạn có thể truy cập $TENOR_API_KEY (hoặc os.environ["TENOR_API_KEY"] bằng Python) mà người dùng không cần phải định cấu hình thêm bất kỳ điều gì. Xem Truyền qua biến môi trường để biết chi tiết.

preconditions.env_vars kế thừa vẫn được hỗ trợ dưới dạng bí danh tương thích ngược.

Cài đặt cấu hình (config.yaml)​

Các kỹ năng có thể khai báo các cài đặt không bí mật được lưu trữ trong config.yaml trong không gian tên skills.config. Không giống như các biến môi trường (là các bí mật được lưu trữ trong .env), cài đặt cấu hình dành cho đường dẫn, tùy chọn và các giá trị không nhạy cảm khác.

metadata:
  hermes:
    config:
      - key: wiki.path
        description: Path to the LLM Wiki knowledge base directory
        default: "~/wiki"
        prompt: Wiki directory path
      - key: wiki.domain
        description: Domain the wiki covers
        default: ""
        prompt: Wiki domain (e.g., AI/ML research)

Mỗi mục hỗ trợ:

  • key (bắt buộc) — dotpath cho cài đặt (ví dụ: wiki.path)
  • description (bắt buộc) — giải thích những gì cài đặt kiểm soát
  • default (tùy chọn) — giá trị mặc định nếu người dùng không định cấu hình nó
  • prompt (tùy chọn) — văn bản nhắc nhở được hiển thị trong quá trình di chuyển cấu hình hermes; quay trở lại mô tả`

Cách thức hoạt động:

  1. Bộ nhớ: Các giá trị được ghi vào config.yaml trong skills.config.<key>:

    skills:
      config:
        wiki:
          path: ~/my-research

  2. Khám phá: hermes config di chuyển quét tất cả các kỹ năng đã bật, tìm các cài đặt chưa được định cấu hình và nhắc người dùng. Cài đặt cũng xuất hiện trong hermes config show trong "Cài đặt kỹ năng".

  3. Chèn thời gian chạy: Khi một kỹ năng tải, các giá trị cấu hình của nó sẽ được phân giải và thêm vào thông báo kỹ năng:

    [Skill config (from ~/.hermes/config.yaml):
      wiki.path = /home/user/my-research
    ]

Tác nhân nhìn thấy các giá trị được định cấu hình mà không cần phải đọc config.yaml.

  1. Thiết lập thủ công: Người dùng cũng có thể đặt giá trị trực tiếp: 
    hermes config set skills.config.wiki.path ~/my-wiki
When to use which

Sử dụng required_environment_variables cho khóa API, mã thông báo và bí mật khác (được lưu trữ trong ~/.hermes/.env, không bao giờ được hiển thị cho mô hình). Sử dụng config cho đường dẫn, tùy chọn và cài đặt không nhạy cảm (được lưu trữ trong config.yaml, hiển thị trong chương trình cấu hình).

Yêu cầu về tệp thông tin xác thực (Mã thông báo OAuth, v.v.)​

Các kỹ năng sử dụng OAuth hoặc thông tin xác thực dựa trên tệp có thể khai báo các tệp cần được gắn vào hộp cát từ xa. Đây là thông tin xác thực được lưu trữ dưới dạng tệp (không phải env vars) — thường là các tệp mã thông báo OAuth được tạo bởi tập lệnh thiết lập.

required_credential_files:
  - path: google_token.json
    description: Google OAuth2 token (created by setup script)
  - path: google_client_secret.json
    description: Google OAuth2 client credentials

Mỗi mục hỗ trợ:

  • path (bắt buộc) — đường dẫn tệp liên quan đến ~/.hermes/
  • description (tùy chọn) — giải thích tập tin là gì và nó được tạo như thế nào

Khi được tải, Hermes sẽ kiểm tra xem các tệp này có tồn tại hay không. Thiếu tệp kích hoạt setup_ Need. Các tập tin hiện có sẽ tự động:

  • Được gắn vào các vùng chứa Docker dưới dạng các liên kết gắn kết chỉ đọc
  • Được đồng bộ hóa vào các hộp cát Modal (lúc tạo + trước mỗi lệnh, vì vậy OAuth giữa phiên sẽ hoạt động)
  • Có sẵn trên chương trình phụ trợ cục bộ mà không cần bất kỳ xử lý đặc biệt nào
When to use which

Sử dụng required_environment_variables cho các khóa và mã thông báo API đơn giản (chuỗi được lưu trữ trong ~/.hermes/.env). Sử dụng required_credential_files cho các tệp mã thông báo OAuth, bí mật ứng dụng khách, JSON của tài khoản dịch vụ, chứng chỉ hoặc bất kỳ thông tin xác thực nào là tệp trên đĩa.

Hãy xem skills/productivity/google-workspace/SKILL.md để biết ví dụ hoàn chỉnh khi sử dụng cả hai.

Hướng dẫn kỹ năng​

Không phụ thuộc bên ngoài​

Ưu tiên stdlib Python, Curl và các công cụ Hermes hiện có (web_extract, terminal, read_file). Nếu cần có phần phụ thuộc, hãy ghi lại các bước cài đặt trong kỹ năng.

Tiết lộ dần dần​

Đặt quy trình công việc phổ biến nhất lên hàng đầu. Các trường hợp Edge và cách sử dụng nâng cao nằm ở phía dưới. Điều này giúp mức sử dụng mã thông báo ở mức thấp cho các tác vụ thông thường.

Bao gồm tập lệnh trợ giúp​

Đối với phân tích cú pháp XML/JSON hoặc logic phức tạp, hãy bao gồm các tập lệnh trợ giúp trong scripts/ — đừng mong đợi LLM luôn ghi nội tuyến các trình phân tích cú pháp.

Kiểm tra nó​

Chạy kỹ năng và xác minh tác nhân thực hiện đúng hướng dẫn:

hermes chat --toolsets skills -q "Use the X skill to do Y"

Kỹ năng nên sống ở đâu?​

Các kỹ năng đi kèm (trong skills/) đi kèm với mỗi lần cài đặt Hermes. Chúng sẽ hữu ích rộng rãi cho hầu hết người dùng:

  • Xử lý tài liệu, nghiên cứu web, quy trình làm việc chung của nhà phát triển, quản trị hệ thống
  • Được nhiều người sử dụng thường xuyên

Nếu kỹ năng của bạn là chính thức và hữu ích nhưng không cần thiết trên toàn cầu (ví dụ: tích hợp dịch vụ phải trả phí, phần phụ thuộc nặng), hãy đặt kỹ năng đó vào tuỳ chọn-kỹ năng/ — nó được gửi cùng với kho lưu trữ, có thể được khám phá thông qua hermes kỹ năng duyệt (được gắn nhãn "chính thức") và cài đặt với sự tin cậy tích hợp.

Nếu kỹ năng của bạn là chuyên biệt, do cộng đồng đóng góp hoặc thích hợp thì kỹ năng đó phù hợp hơn với Trung tâm kỹ năng — tải nó lên cơ quan đăng ký và chia sẻ nó thông qua hermes Skills install.

Kỹ năng xuất bản​

Đến Trung tâm Kỹ năng​

hermes skills publish skills/my-skill --to github --repo owner/repo

Đến kho lưu trữ tùy chỉnh​

Thêm kho lưu trữ của bạn dưới dạng một lần nhấn:

hermes skills tap add owner/repo

Sau đó, người dùng có thể tìm kiếm và cài đặt từ kho lưu trữ của bạn.

Quét bảo mật​

Tất cả các kỹ năng do trung tâm cài đặt đều phải trải qua một trình quét bảo mật để kiểm tra:

  • Các mẫu lọc dữ liệu
  • Nỗ lực tiêm nhắc
  • Lệnh hủy diệt
  • Phun vỏ

Mức độ tin cậy:

  • buildin — giao hàng với Hermes (luôn được tin cậy)
  • chính thức — từ các kỹ năng tùy chọn/ trong repo (tin cậy tích hợp, không có cảnh báo của bên thứ ba)
  • đáng tin cậy — từ openai/skills, anthropics/skills
  • cộng đồng — những phát hiện không nguy hiểm có thể được ghi đè bằng --force; phán quyết nguy hiểm vẫn bị chặn

Hermes hiện có thể sử dụng các kỹ năng của bên thứ ba từ nhiều mô hình khám phá bên ngoài:

  • số nhận dạng GitHub trực tiếp (ví dụ: openai/skills/k8s)
  • Mã định danh skills.sh (ví dụ: skills-sh/vercel-labs/json-render/json-render-react)
  • điểm cuối nổi tiếng được cung cấp từ /.well-known/skills/index.json

Nếu bạn muốn mọi người có thể khám phá các kỹ năng của mình mà không cần trình cài đặt dành riêng cho GitHub, hãy cân nhắc việc cung cấp chúng từ một điểm cuối nổi tiếng bên cạnh việc xuất bản chúng trên kho lưu trữ hoặc thị trường.