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 gồm 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 đi kèm 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 optional-skills/ :

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 platforms:

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 ẩ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ực	Hành vi
requires_toolsets	Kỹ năng bị ẩn khi BẤT KỲ bộ công cụ nào được liệt kê không có sẵn
requires_tools	Kỹ năng bị ẩn khi BẤT KỲ công cụ nào được liệt kê không có sẵn
fallback_for_toolsets	Kỹ năng bị ẩn khi BẤT KỲ bộ công cụ nào được liệt kê **có sẵn
fallback_for_tools	Kỹ 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ý dữ liệu web bằng requires_toolsets: [web] sẽ không làm lộn xộn lời nhắc khi tắt công cụ web.

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 cần thiết 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` :

```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.

Chuyển qua hộp cát

Khi kỹ năng của bạn được tải, mọi required_environment_variables đã được khai báo 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 biến môi trường để biết chi tiết.

Kế thừa prerequisites.env_vars 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 dưới 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 hermes config migrate ; quay trở lại description

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 migrate 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 đọc chính config.yaml.

4. 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

Khi nào nên sử dụng cái nào

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 là gì và cách tạo tệp

Khi được tải, Hermes sẽ kiểm tra xem các tệp này có tồn tại hay không. Trình kích hoạt tệp bị thiếu setup_needed . 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

Khi nào nên sử dụng cái nào

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.

Xem skills/productivity/google-workspace/SKILL.md để biết ví dụ hoàn chỉnh bằng cách 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/ ) được cung cấp cùng 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ụ thuộc nặng), hãy đặt kỹ năng đó vào ** optional-skills/ ** — kỹ năng này được gửi cùng với kho lưu trữ, có thể tìm thấy được thông qua hermes skills browse (đượ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 môn, do cộng đồng đóng góp hoặc thích hợp thì kỹ năng đó sẽ 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ó 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:
• builtin — giao hàng với Hermes (luôn được tin cậy)
• official — từ optional-skills/ trong kho lưu trữ (tin cậy tích hợp, không có cảnh báo của bên thứ ba)
• trusted — từ openai/kỹ năng, nhân chủng học/kỹ năng
• community — những phát hiện không nguy hiểm có thể được ghi đè bằng --force ; dangerous phán quyết 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 phục vụ 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.