~/.hermes/skills/
├── category-a/
│   └── skill-name/
│       ├── SKILL.md              # 必需：主文件
│       ├── references/           # 可選：參考資料
│       ├── templates/            # 可選：模板文件
│       ├── scripts/              # 可選：腳本文件
│       └── assets/               # 可選：資源文件
├── category-b/
│   └── another-skill/
│       └── SKILL.md
└── ...

get_all_skills_dirs()
  ├── ~/.hermes/skills/           # 本地目錄（始終在前）
  └── skills.external_dirs        # 外部目錄（config.yaml配置）
       ↓
iter_skill_index_files()          # 遞歸掃描所有 SKILL.md
       ↓
parse_frontmatter()               # 解析 YAML 元數(shù)據(jù)
       ↓
過濾規(guī)則：
  ├── skill_matches_platform()    # 平臺兼容性檢查
  ├── get_disabled_skill_names()  # 禁用列表過濾
  └── _skill_should_show()        # 條件激活規(guī)則
       ↓
build_skills_system_prompt()      # 生成分類索引 Prompt

## Skills (mandatory)
Before replying, scan the skills below. If a skill matches or is even partially relevant
to your task, you MUST load it with skill_view(name) and follow its instructions.

<available_skills>
  category-a:
    - skill-name: brief description
    - another-skill: another description
</available_skills>

Only proceed without loading a skill if genuinely none are relevant to the task.

System Prompt 引導:
"Before replying, scan the skills below... MUST load with skill_view(name)"
       ↓
LLM 判斷任務與 skill 相關
       ↓
tool_call: skill_view(name="skill-name")

用戶輸入: /skill-name some instruction
       ↓
scan_skill_commands()           # 掃描所有 SKILL.md 生成命令映射
       ↓
匹配 /skill-name
       ↓
build_skill_invocation_message() # 構(gòu)建觸發(fā)消息

hermes --skills skill-name

build_preloaded_skills_prompt()
       ↓
注入到 session prompt 開頭

skill_view(name)
  ├── 解析 qualified name          # plugin:skill → 路由到 plugin 系統(tǒng)
  ├── 目錄搜索（first match wins） # local → external
  │   ├── 直接路徑: search_dir/name/SKILL.md
  │   ├── 分類路徑: search_dir/category/name/SKILL.md
  │   └── 名稱匹配: 遍歷所有 SKILL.md 比對目錄名
  ├── 安全檢查
  │   ├── 路徑穿越檢測（防止 .. 攻擊）
  │   └── prompt injection 模式掃描
  ├── 平臺/禁用檢查
  ├── 前置條件檢查
  │   ├── 環(huán)境變量（prerequisites.env）
  │   └── 憑證文件（prerequisites.credential_files）
  ├── preprocess_skill_content()
  │   ├── 模板變量替換: ${HERMES_SKILL_DIR} → 絕對路徑
  │   └── inline shell 展開: !`cmd` → 執(zhí)行結(jié)果
  ├── 收集 linked_files
  │   ├── references/*.md
  │   ├── templates/*.yaml
  │   ├── scripts/*.py
  │   └── assets/*
  └── 返回 JSON:
      {
        "success": true,
        "name": "skill-name",
        "content": "<SKILL.md 完整內(nèi)容>",
        "linked_files": {"references": [...], "templates": [...]},
        "skill_dir": "/path/to/skill",
        "setup_needed": false,
        "readiness_status": "available"
      }

${HERMES_SKILL_DIR}     → skill 的絕對路徑
${HERMES_SESSION_ID}    → 當前會話 ID

!`ls -la ${HERMES_SKILL_DIR}/scripts/`
→ 替換為命令執(zhí)行結(jié)果

tool 返回 JSON
       ↓
作為 tool_result 注入 conversation history
       ↓
LLM 在下一輪看到完整 skill 內(nèi)容

_build_skill_message()
  ├── [IMPORTANT: The user has invoked the "xxx" skill...]
  ├── <SKILL.md 完整內(nèi)容（已預處理）>
  ├── [Skill directory: /path/to/skill]
  ├── [Skill config: key = value]        # 配置變量注入
  ├── [Skill setup note: ...]            # 安裝提示
  ├── [This skill has supporting files:] # 支持文件列表
  │   ├── references/api.md → /path/to/references/api.md
  │   └── scripts/run.py → /path/to/scripts/run.py
  └── The user has provided the following instruction: ...
       ↓
作為 user message 注入 → LLM 響應

[IMPORTANT: The user launched this CLI session with "xxx" ...]
<SKILL.md 完整內(nèi)容>
       ↓
追加到 system prompt 的 prompt_parts

LLM 接收包含 skill 內(nèi)容的 message
  ├── 遵循 skill 中的 instructions
  ├── 可通過 skill_view(name, file_path) 加載 supporting files
  ├── 執(zhí)行 skill 中的 scripts（通過 skill_dir 絕對路徑）
  ├── 使用 skill 聲明的配置變量
  └── 任務完成后可選：skill_manage(action='patch') 更新 skill

---
name: skill-name
description: "簡短描述（≤1024字符）"
version: 1.0.0
author: Author Name
license: MIT
platforms: [macos, linux]  # 可選：平臺限制
metadata:
  hermes:
    tags: [tag1, tag2]
    related_skills: [skill-a, skill-b]
    fallback_for_toolsets: [web]     # 當 web toolset 可用時隱藏
    fallback_for_tools: [web_fetch]  # 當 web_fetch tool 可用時隱藏
    requires_toolsets: [browser]     # 當 browser toolset 不可用時隱藏
    requires_tools: [browser_click]  # 當 browser_click tool 不可用時隱藏
    config:                          # 配置變量聲明
      - key: api_endpoint
        description: API endpoint URL
        default: "https://api.example.com"
        prompt: Enter API endpoint
prerequisites:
  env:
    - name: API_KEY
      description: API key for authentication
  credential_files:
    - path: ~/.config/skill/credentials.json
      description: Credentials file
---