Tạo kỹ năng

#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 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 có 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

`markdown

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

:

``` yaml
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 này 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.

`YAML
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ý 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 qua 
`skill_view

, các biến cần thiết của nó sẽ tự động được đăng ký để chuyển vào môi trường thực thi hộp cát (terminal, exec_code).

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

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

:::tip[Sandbox Passthrough]
Khi kỹ năng của bạn được tải, mọi 
`required_environment_variables
` đã được thiết lập sẽ **tự động được chuyển qua** tới các hộp cát 
`execute_code
` và 
`terminal
` — bao gồm 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 [Environment Variable Passthrough](/docs/user-guide/security#environment-variable-passthrough) để biết chi tiết.
:::

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

``` yaml
metadata:
  Hermes:
    config:

      - key: myplugin.path
        description: Path to the plugin data directory
        default: "~/myplugin-data"
        prompt: Plugin data directory path
      - key: myplugin.domain
        description: Domain the plugin operates on
        default: ""
        prompt: Plugin domain (e.g., AI/ML research)

`
``Mỗi mục hỗ trợ:
- 
`key
` (bắt buộc) — dotpath cho cài đặt (ví dụ: 
`myplugin.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. **Lưu trữ:** Các giá trị được ghi vào 
`config.yaml
` theo 
`skills.config.<key

:

``` yaml
   skills:
     config:
       myplugin:
         path: ~/my-data

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):
     myplugin.path = /home/user/my-data
   ]

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

`bash
   Hermes config set skills.config.myplugin.path ~/my-data

:::tip[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.

``` yaml
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. Thiếu tệp kích hoạt 
`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

:::tip[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.
:::

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.

### Cung cấp phương tiện dưới dạng tài liệu (

[[as_document]]

)

Nếu kỹ năng của bạn tạo ra ảnh chụp màn hình, biểu đồ hoặc bất kỳ hình ảnh nào có độ phân giải cao mà việc nén bản xem trước bị mất sẽ gây tổn hại - hãy đưa ra lệnh theo nghĩa đen 

[[as_document]]
` ở đâu đó trong phản hồi (thường là dòng cuối cùng). Cổng loại bỏ lệnh này và phân phối mọi đường dẫn phương tiện được trích xuất trong phản hồi đó dưới dạng tệp đính kèm có thể tải xuống thay vì bong bóng hình ảnh nội tuyến. Xem [Skill output and media delivery](../user-guide/features/skills.md#skill-output-and-media-delivery) để biết ngữ nghĩa đầy đủ.

#### Tham khảo các tập lệnh đi kèm từ SKILL.md

Khi một kỹ năng được tải, thông báo kích hoạt sẽ hiển thị thư mục kỹ năng tuyệt đối dưới dạng 

[Skill directory: /abs/path]
` và cũng thay thế hai mã thông báo mẫu ở bất kỳ đâu trong nội dung SKILL.md:

| Mã thông báo | Được thay thế bằng |
|---|---|
| 

$\{Hermes_SKILL_DIR}
` | Đường dẫn tuyệt đối đến thư mục kỹ năng |
| 

$\{Hermes_SESSION_ID}
` | Id phiên hoạt động (được giữ nguyên nếu không có phiên) |

Vì vậy, SKILL.md có thể yêu cầu tác nhân chạy tập lệnh đi kèm trực tiếp với:

`markdown
To analyse the input, run:

node $\{Hermes_SKILL_DIR}/scripts/analyse.js <input>

`
`Tác nhân nhìn thấy đường dẫn tuyệt đối được thay thế và gọi công cụ 
`terminal
` bằng lệnh sẵn sàng chạy — không cần tính toán đường dẫn, không cần thực hiện chuyến đi khứ hồi 
`skill_view
` bổ sung. Vô hiệu hóa tính năng thay thế trên toàn cầu bằng 
`skills.template_vars: false
` trong 
`config.yaml

.

#### Đoạn mã shell nội tuyến (chọn tham gia)

Các kỹ năng cũng có thể nhúng các đoạn mã shell nội tuyến được viết dưới dạng 

` !
``` cmd
` 

` trong phần nội dung SKILL.md. Khi được bật, thiết bị xuất chuẩn của mỗi đoạn mã sẽ được đưa vào tin nhắn trước khi tổng đài viên đọc nó, vì vậy các kỹ năng có thể đưa vào ngữ cảnh động:

`markdown
Current date: !
`date -u +%Y-%m-%d

Git branch: !
`git -C $\{Hermes_SKILL_DIR} rev-parse --abbrev-ref HEAD

`

``Tính năng này **tắt theo mặc định** — bất kỳ đoạn mã nào trong SKILL.md đều chạy trên máy chủ mà không được phê duyệt, vì vậy chỉ bật đoạn mã đó cho các nguồn kỹ năng mà bạn tin cậy:

`YAML

# config.yaml
skills:
  inline_shell: true
  inline_shell_timeout: 10   # seconds per snippet

`
``Các đoạn mã chạy với thư mục kỹ năng làm thư mục làm việc và đầu ra được giới hạn ở 4000 ký tự. Các lỗi (hết thời gian, số lần thoát khác 0) hiển thị dưới dạng điểm đánh dấu 

[inline-shell error: ...]
` ngắn thay vì phá vỡ toàn bộ kỹ năng.

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

``` bash
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 **
`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 độ 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 đó 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

``` bash
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:

`bash
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 repo (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 loại/kỹ năng, ôm mặt/kỹ năng
- 
`community

 - những phát hiện không nguy hiểm có thể được ghi đè bằng 

--force

; Các phán quyết 
`dangerous
` 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.