better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/webhook-github-pr-review.md

@@ -0,0 +1,329 @@
+---
+sidebar_position: 11
+sidebar_label: "通过 Webhook 进行 GitHub PR 审查"
+title: "使用 Webhook 自动发布 GitHub PR 评论"
+description: "将 Hermes 连接到 GitHub，使其自动获取 PR diff、审查代码变更并发布评论——由 webhook 触发，无需手动提示"
+---
+
+# 使用 Webhook 自动发布 GitHub PR 评论
+
+本指南介绍如何将 Hermes Agent 连接到 GitHub，使其自动获取 pull request 的 diff、分析代码变更并发布评论——由 webhook 事件触发，无需手动 prompt（提示词）。
+
+当 PR 被打开或更新时，GitHub 会向你的 Hermes 实例发送一个 webhook POST 请求。Hermes 使用一个 prompt 运行 agent，该 prompt 指示其通过 `gh` CLI 获取 diff，并将响应发布回 PR 线程。
+
+:::tip 想要无需公网端点的更简单配置？
+如果你没有公网 URL，或只是想快速上手，请查看 [构建 GitHub PR 审查 Agent](./github-pr-review-agent.md) —— 使用 cron 作业按计划轮询 PR，可在 NAT 和防火墙后运行。
+:::
+
+:::info 参考文档
+完整的 webhook 平台参考（所有配置选项、投递类型、动态订阅、安全模型），请参阅 [Webhooks](/user-guide/messaging/webhooks)。
+:::
+
+:::warning Prompt 注入风险
+Webhook payload 包含攻击者可控的数据——PR 标题、commit 消息和描述中可能包含恶意指令。当你的 webhook 端点暴露在公网时，请在沙箱环境（Docker、SSH 后端）中运行 gateway。请参阅下方的[安全说明](#security-notes)。
+:::
+
+---
+
+## 前提条件
+
+- Hermes Agent 已安装并运行（`hermes gateway`）
+- [`gh` CLI](https://cli.github.com/) 已安装并在 gateway 主机上完成认证（`gh auth login`）
+- 你的 Hermes 实例有一个可公网访问的 URL（如果在本地运行，请参阅[使用 ngrok 进行本地测试](#local-testing-with-ngrok)）
+- 对 GitHub 仓库的管理员权限（管理 webhook 所需）
+
+---
+
+## 第一步——启用 webhook 平台
+
+在你的 `~/.hermes/config.yaml` 中添加以下内容：
+
+```yaml
+platforms:
+  webhook:
+    enabled: true
+    extra:
+      port: 8644          # 默认值；如果该端口被其他服务占用，请修改
+      rate_limit: 30      # 每条路由每分钟最大请求数（非全局上限）
+
+      routes:
+        github-pr-review:
+          secret: "your-webhook-secret-here"   # 必须与 GitHub webhook secret 完全一致
+          events:
+            - pull_request
+
+          # agent 被指示在审查前先获取实际的 diff。
+          # {number} 和 {repository.full_name} 从 GitHub payload 中解析。
+          prompt: |
+            A pull request event was received (action: {action}).
+
+            PR #{number}: {pull_request.title}
+            Author: {pull_request.user.login}
+            Branch: {pull_request.head.ref} → {pull_request.base.ref}
+            Description: {pull_request.body}
+            URL: {pull_request.html_url}
+
+            If the action is "closed" or "labeled", stop here and do not post a comment.
+
+            Otherwise:
+            1. Run: gh pr diff {number} --repo {repository.full_name}
+            2. Review the code changes for correctness, security issues, and clarity.
+            3. Write a concise, actionable review comment and post it.
+
+          deliver: github_comment
+          deliver_extra:
+            repo: "{repository.full_name}"
+            pr_number: "{number}"
+```
+
+**关键字段：**
+
+| 字段 | 说明 |
+|---|---|
+| `secret`（路由级别） | 该路由的 HMAC secret。如果省略，则回退到 `extra.secret` 全局配置。 |
+| `events` | 要接受的 `X-GitHub-Event` 请求头值列表。空列表 = 接受所有。 |
+| `prompt` | 模板；`{field}` 和 `{nested.field}` 从 GitHub payload 中解析。 |
+| `deliver` | `github_comment` 通过 `gh pr comment` 发布。`log` 仅写入 gateway 日志。 |
+| `deliver_extra.repo` | 从 payload 中解析为例如 `org/repo`。 |
+| `deliver_extra.pr_number` | 从 payload 中解析为 PR 编号。 |
+
+:::note Payload 中不包含代码
+GitHub webhook payload 包含 PR 元数据（标题、描述、分支名、URL），但**不包含 diff**。上方的 prompt 指示 agent 运行 `gh pr diff` 来获取实际变更。`terminal` 工具已包含在默认的 `hermes-webhook` 工具集中，无需额外配置。
+:::
+
+---
+
+## 第二步——启动 gateway
+
+```bash
+hermes gateway
+```
+
+你应该看到：
+
+```
+[webhook] Listening on 0.0.0.0:8644 — routes: github-pr-review
+```
+
+验证其是否正在运行：
+
+```bash
+curl http://localhost:8644/health
+# {"status": "ok", "platform": "webhook"}
+```
+
+---
+
+## 第三步——在 GitHub 上注册 webhook
+
+1. 进入你的仓库 → **Settings** → **Webhooks** → **Add webhook**
+2. 填写：
+   - **Payload URL：** `https://your-public-url.example.com/webhooks/github-pr-review`
+   - **Content type：** `application/json`
+   - **Secret：** 与路由配置中 `secret` 设置的值相同
+   - **Which events?** → 选择单个事件 → 勾选 **Pull requests**
+3. 点击 **Add webhook**
+
+GitHub 会立即发送一个 `ping` 事件以确认连接。该事件会被安全忽略——`ping` 不在你的 `events` 列表中——并返回 `{"status": "ignored", "event": "ping"}`。它仅在 DEBUG 级别记录日志，因此不会在默认日志级别的控制台中显示。
+
+---
+
+## 第四步——打开一个测试 PR
+
+创建一个分支，推送一个变更，并打开一个 PR。在 30–90 秒内（取决于 PR 大小和模型），Hermes 应该会发布一条审查评论。
+
+要实时跟踪 agent 的进度：
+
+```bash
+tail -f "${HERMES_HOME:-$HOME/.hermes}/logs/gateway.log"
+```
+
+---
+
+## 使用 ngrok 进行本地测试
+
+如果 Hermes 在你的笔记本上运行，使用 [ngrok](https://ngrok.com/) 将其暴露到公网：
+
+```bash
+ngrok http 8644
+```
+
+复制 `https://...ngrok-free.app` URL 并将其用作你的 GitHub Payload URL。在 ngrok 免费版中，每次 ngrok 重启后 URL 都会变化——每次会话都需要更新你的 GitHub webhook。付费 ngrok 账户可获得静态域名。
+
+你可以直接用 `curl` 对静态路由进行冒烟测试——无需 GitHub 账户或真实 PR。
+
+:::tip 本地测试时使用 `deliver: log`
+在测试时，将配置中的 `deliver: github_comment` 改为 `deliver: log`。否则 agent 将尝试向测试 payload 中的假 `org/repo#99` 仓库发布评论，这将会失败。对 prompt 输出满意后，再切换回 `deliver: github_comment`。
+:::
+
+```bash
+SECRET="your-webhook-secret-here"
+BODY='{"action":"opened","number":99,"pull_request":{"title":"Test PR","body":"Adds a feature.","user":{"login":"testuser"},"head":{"ref":"feat/x"},"base":{"ref":"main"},"html_url":"https://github.com/org/repo/pull/99"},"repository":{"full_name":"org/repo"}}'
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print "sha256="$2}')
+
+curl -s -X POST http://localhost:8644/webhooks/github-pr-review \
+  -H "Content-Type: application/json" \
+  -H "X-GitHub-Event: pull_request" \
+  -H "X-Hub-Signature-256: $SIG" \
+  -d "$BODY"
+# Expected: {"status":"accepted","route":"github-pr-review","event":"pull_request","delivery_id":"..."}
+```
+
+然后观察 agent 运行：
+```bash
+tail -f "${HERMES_HOME:-$HOME/.hermes}/logs/gateway.log"
+```
+
+:::note
+`hermes webhook test <name>` 仅适用于通过 `hermes webhook subscribe` 创建的**动态订阅**。它不读取 `config.yaml` 中的路由。
+:::
+
+---
+
+## 过滤特定 action
+
+GitHub 会针对多种 action 发送 `pull_request` 事件：`opened`、`synchronize`、`reopened`、`closed`、`labeled` 等。`events` 列表仅按 `X-GitHub-Event` 请求头值过滤——无法在路由级别按 action 子类型过滤。
+
+第一步中的 prompt 已通过指示 agent 对 `closed` 和 `labeled` 事件提前停止来处理这一问题。
+
+:::warning Agent 仍会运行并消耗 token（令牌）
+"stop here" 指令会阻止有意义的审查，但无论 action 如何，agent 仍会对每个 `pull_request` 事件运行至完成。GitHub webhook 只能按事件类型（`pull_request`、`push`、`issues` 等）过滤——无法按 action 子类型（`opened`、`closed`、`labeled`）过滤。路由级别没有针对子 action 的过滤器。对于高流量仓库，请接受这一成本，或通过 GitHub Actions workflow 在上游进行过滤，有条件地调用你的 webhook URL。
+:::
+
+> 不支持 Jinja2 或条件模板语法。`{field}` 和 `{nested.field}` 是唯一支持的替换方式。其他内容会原样传递给 agent。
+
+---
+
+## 使用 skill 保持一致的审查风格
+
+加载一个 [Hermes skill](/user-guide/features/skills) 以赋予 agent 一致的审查风格。在 `config.yaml` 的 `platforms.webhook.extra.routes` 中，向你的路由添加 `skills`：
+
+```yaml
+platforms:
+  webhook:
+    enabled: true
+    extra:
+      routes:
+        github-pr-review:
+          secret: "your-webhook-secret-here"
+          events: [pull_request]
+          prompt: |
+            A pull request event was received (action: {action}).
+            PR #{number}: {pull_request.title} by {pull_request.user.login}
+            URL: {pull_request.html_url}
+
+            If the action is "closed" or "labeled", stop here and do not post a comment.
+
+            Otherwise:
+            1. Run: gh pr diff {number} --repo {repository.full_name}
+            2. Review the diff using your review guidelines.
+            3. Write a concise, actionable review comment and post it.
+          skills:
+            - review
+          deliver: github_comment
+          deliver_extra:
+            repo: "{repository.full_name}"
+            pr_number: "{number}"
+```
+
+> **注意：** 列表中只有第一个找到的 skill 会被加载。Hermes 不会叠加多个 skill——后续条目会被忽略。
+
+---
+
+## 将响应发送到 Slack 或 Discord
+
+将路由中的 `deliver` 和 `deliver_extra` 字段替换为你的目标平台：
+
+```yaml
+# 在 platforms.webhook.extra.routes.<route-name> 内部：
+
+# Slack
+deliver: slack
+deliver_extra:
+  chat_id: "C0123456789"   # Slack 频道 ID（省略则使用配置的默认频道）
+
+# Discord
+deliver: discord
+deliver_extra:
+  chat_id: "987654321012345678"  # Discord 频道 ID（省略则使用默认频道）
+```
+
+目标平台也必须在 gateway 中启用并连接。如果省略 `chat_id`，响应将发送到该平台配置的默认频道。
+
+有效的 `deliver` 值：`log` · `github_comment` · `telegram` · `discord` · `slack` · `signal` · `sms`
+
+---
+
+## GitLab 支持
+
+同一适配器也适用于 GitLab。GitLab 使用 `X-Gitlab-Token` 进行认证（纯字符串匹配，非 HMAC）——Hermes 会自动处理两者。
+
+对于事件过滤，GitLab 将 `X-GitLab-Event` 设置为 `Merge Request Hook`、`Push Hook`、`Pipeline Hook` 等值。在 `events` 中使用精确的请求头值：
+
+```yaml
+events:
+  - Merge Request Hook
+```
+
+GitLab 的 payload 字段与 GitHub 不同——例如，MR 标题使用 `{object_attributes.title}`，MR 编号使用 `{object_attributes.iid}`。发现完整 payload 结构最简单的方式是使用 GitLab webhook 设置中的 **Test** 按钮，结合 **Recent Deliveries** 日志。或者，在路由配置中省略 `prompt`——Hermes 将把完整 payload 作为格式化 JSON 直接传递给 agent，agent 的响应（在 gateway 日志中通过 `deliver: log` 可见）将描述其结构。
+
+---
+
+## 安全说明
+
+- **永远不要在生产环境中使用 `INSECURE_NO_AUTH`**——它会完全禁用签名验证。仅用于本地开发。
+- **定期轮换你的 webhook secret**，并在 GitHub（webhook 设置）和你的 `config.yaml` 中同步更新。
+- **速率限制**默认为每条路由每分钟 30 次请求（可通过 `extra.rate_limit` 配置）。超出限制返回 `429`。
+- **重复投递**（webhook 重试）通过 1 小时的幂等性缓存进行去重。缓存键依次为 `X-GitHub-Delivery`（如果存在）、`X-Request-ID`、毫秒级时间戳。当两个投递 ID 请求头都未设置时，重试**不会**去重。
+- **Prompt 注入：** PR 标题、描述和 commit 消息均为攻击者可控内容。恶意 PR 可能尝试操纵 agent 的行为。当暴露在公网时，请在沙箱环境（Docker、VM）中运行 gateway。
+
+---
+
+## 故障排查
+
+| 现象 | 检查项 |
+|---|---|
+| `401 Invalid signature` | config.yaml 中的 secret 与 GitHub webhook secret 不匹配 |
+| `404 Unknown route` | URL 中的路由名称与 `routes:` 中的键不匹配 |
+| `429 Rate limit exceeded` | 每条路由每分钟 30 次请求已超出——在 GitHub UI 中重新投递测试事件时常见；等待一分钟或提高 `extra.rate_limit` |
+| 未发布评论 | `gh` 未安装、不在 PATH 中，或未完成认证（`gh auth login`） |
+| Agent 运行但无评论 | 检查 gateway 日志——如果 agent 输出为空或仅为"SKIP"，投递仍会被尝试 |
+| 端口已被占用 | 在 config.yaml 中修改 `extra.port` |
+| Agent 运行但仅审查了 PR 描述 | prompt 中未包含 `gh pr diff` 指令——diff 不在 webhook payload 中 |
+| 看不到 ping 事件 | 被忽略的事件仅在 DEBUG 日志级别返回 `{"status":"ignored","event":"ping"}`——检查 GitHub 的投递日志（仓库 → Settings → Webhooks → 你的 webhook → Recent Deliveries） |
+
+**GitHub 的 Recent Deliveries 标签页**（仓库 → Settings → Webhooks → 你的 webhook）显示每次投递的精确请求头、payload、HTTP 状态和响应体。这是无需查看服务器日志即可诊断故障的最快方式。
+
+---
+
+## 完整配置参考
+
+```yaml
+platforms:
+  webhook:
+    enabled: true
+    extra:
+      host: "0.0.0.0"         # 绑定地址（默认：0.0.0.0）
+      port: 8644               # 监听端口（默认：8644）
+      secret: ""               # 可选的全局回退 secret
+      rate_limit: 30           # 每条路由每分钟请求数
+      max_body_bytes: 1048576  # payload 大小限制，单位字节（默认：1 MB）
+
+      routes:
+        <route-name>:
+          secret: "required-per-route"
+          events: []            # [] = 接受所有；否则列出 X-GitHub-Event 值
+          prompt: ""            # {field} / {nested.field} 从 payload 中解析
+          skills: []            # 加载第一个匹配的 skill（仅一个）
+          deliver: "log"        # log | github_comment | telegram | discord | slack | signal | sms
+          deliver_extra: {}     # github_comment 需要 repo + pr_number；其他平台需要 chat_id
+```
+
+---
+
+## 下一步
+
+- **[基于 Cron 的 PR 审查](./github-pr-review-agent.md)** —— 按计划轮询 PR，无需公网端点
+- **[Webhook 参考](/user-guide/messaging/webhooks)** —— webhook 平台的完整配置参考
+- **[构建 Plugin](/developer-guide/plugins)** —— 将审查逻辑打包为可共享的 plugin
+- **[Profiles](/user-guide/profiles)** —— 运行一个拥有独立内存和配置的专属审查者 profile

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/work-with-skills.md

@@ -0,0 +1,290 @@
+---
+sidebar_position: 12
+title: "使用 Skills"
+description: "查找、安装、使用和创建 skills——按需加载的知识文档，用于教会 Hermes 新的工作流程"
+---
+
+# 使用 Skills
+
+Skills（技能）是按需加载的知识文档，用于教会 Hermes 如何处理特定任务——从生成 ASCII 艺术到管理 GitHub PR。本指南介绍日常使用方法。
+
+完整技术参考请见 [Skills 系统](/user-guide/features/skills)。
+
+---
+
+## 查找 Skills
+
+每个 Hermes 安装都内置了捆绑的 skills。查看可用列表：
+
+```bash
+# 在任意聊天会话中：
+/skills
+
+# 或通过 CLI：
+hermes skills list
+```
+
+输出包含名称和描述的紧凑列表：
+
+```
+ascii-art         Generate ASCII art using pyfiglet, cowsay, boxes...
+arxiv             Search and retrieve academic papers from arXiv...
+github-pr-workflow Full PR lifecycle — create branches, commit...
+plan              Plan mode — inspect context, write a markdown...
+excalidraw        Create hand-drawn style diagrams using Excalidraw...
+```
+
+### 搜索 Skill
+
+```bash
+# 按关键词搜索
+/skills search docker
+/skills search music
+```
+
+### Skills Hub
+
+官方可选 skills（较重或小众、默认未激活的 skills）可通过 Hub 获取：
+
+```bash
+# 浏览官方可选 skills
+/skills browse
+
+# 搜索 Hub
+/skills search blockchain
+```
+
+---
+
+## 使用 Skill
+
+每个已安装的 skill 自动成为一个斜杠命令。直接输入其名称即可：
+
+```bash
+# 加载 skill 并指定任务
+/ascii-art Make a banner that says "HELLO WORLD"
+/plan Design a REST API for a todo app
+/github-pr-workflow Create a PR for the auth refactor
+
+# 只输入 skill 名称（不带任务）会加载它并让你描述需求
+/excalidraw
+```
+
+你也可以通过自然对话触发 skills——告诉 Hermes 使用某个特定 skill，它会通过 `skill_view` 工具加载。
+
+### 渐进式加载
+
+Skills 采用 token 高效的加载模式，agent 不会一次性加载所有内容：
+
+1. **`skills_list()`** — 所有 skills 的紧凑列表（约 3k tokens），在会话开始时加载。
+2. **`skill_view(name)`** — 单个 skill 的完整 SKILL.md 内容，在 agent 判断需要该 skill 时加载。
+3. **`skill_view(name, file_path)`** — skill 内的特定参考文件，仅在需要时加载。
+
+这意味着 skills 在真正被使用之前不消耗任何 tokens。
+
+---
+
+## 从 Hub 安装
+
+官方可选 skills 随 Hermes 一起发布，但默认未激活，需显式安装：
+
+```bash
+# 安装官方可选 skill
+hermes skills install official/research/arxiv
+
+# 在聊天会话中从 Hub 安装
+/skills install official/creative/songwriting-and-ai-music
+
+# 从 HTTP(S) URL 安装 SKILL.md 及其引用的支持文件
+hermes skills install https://sharethis.chat/SKILL.md
+/skills install https://example.com/SKILL.md --name my-skill
+```
+
+安装过程：
+1. skill 目录被复制到 `~/.hermes/skills/`
+2. 出现在 `skills_list` 输出中
+3. 成为可用的斜杠命令
+
+:::tip
+已安装的 skills 在新会话中生效。如需在当前会话中立即使用，可用 `/reset` 开启新会话，或添加 `--now` 参数立即使 prompt 缓存失效（下一轮会消耗更多 tokens）。
+:::
+
+### 验证安装
+
+```bash
+# 确认已安装
+hermes skills list | grep arxiv
+
+# 或在聊天中
+/skills search arxiv
+```
+
+---
+
+## 插件提供的 Skills
+
+插件可以使用命名空间名称（`plugin:skill`）捆绑自己的 skills，以避免与内置 skills 发生名称冲突。
+
+```bash
+# 通过限定名称加载插件 skill
+skill_view("superpowers:writing-plans")
+
+# 同名的内置 skill 不受影响
+skill_view("writing-plans")
+```
+
+插件 skills **不会**列在系统 prompt 中，也不出现在 `skills_list` 中。它们是按需加载的——当你知道某个插件提供了某个 skill 时，显式加载它。加载后，agent 会看到一个横幅，列出同一插件的其他 skills。
+
+关于如何在自己的插件中捆绑 skills，请参见 [构建 Hermes 插件 → 捆绑 skills](/developer-guide/plugins#bundle-skills)。
+
+---
+
+## 配置 Skill 设置
+
+部分 skills 在 frontmatter 中声明了所需的配置：
+
+```yaml
+metadata:
+  hermes:
+    config:
+      - key: tenor.api_key
+        description: "Tenor API key for GIF search"
+        prompt: "Enter your Tenor API key"
+        url: "https://developers.google.com/tenor/guides/quickstart"
+```
+
+当带有配置的 skill 首次加载时，Hermes 会提示你输入相应值，并将其存储在 `config.yaml` 的 `skills.config.*` 下。
+
+通过 CLI 管理 skill 配置：
+
+```bash
+# 对特定 skill 进行交互式配置
+hermes skills config gif-search
+
+# 查看所有 skill 配置
+hermes config get skills.config
+```
+
+---
+
+## 创建自己的 Skill
+
+Skills 只是带有 YAML frontmatter 的 Markdown 文件，创建一个不超过五分钟。
+
+### 1. 创建目录
+
+```bash
+mkdir -p ~/.hermes/skills/my-category/my-skill
+```
+
+### 2. 编写 SKILL.md
+
+```markdown title="~/.hermes/skills/my-category/my-skill/SKILL.md"
+---
+name: my-skill
+description: Brief description of what this skill does
+version: 1.0.0
+metadata:
+  hermes:
+    tags: [my-tag, automation]
+    category: my-category
+---
+
+# My Skill
+
+## When to Use
+Use this skill when the user asks about [specific topic] or needs to [specific task].
+
+## Procedure
+1. First, check if [prerequisite] is available
+2. Run `command --with-flags`
+3. Parse the output and present results
+
+## Pitfalls
+- Common failure: [description]. Fix: [solution]
+- Watch out for [edge case]
+
+## Verification
+Run `check-command` to confirm the result is correct.
+```
+
+### 3. 添加参考文件（可选）
+
+Skills 可以包含 agent 按需加载的辅助文件：
+
+```
+my-skill/
+├── SKILL.md                    # 主 skill 文档
+├── references/
+│   ├── api-docs.md             # agent 可查阅的 API 参考
+│   └── examples.md             # 示例输入/输出
+├── templates/
+│   └── config.yaml             # agent 可使用的模板文件
+└── scripts/
+    └── setup.sh                # agent 可执行的脚本
+```
+
+在 SKILL.md 中引用这些文件：
+
+```markdown
+For API details, load the reference: `skill_view("my-skill", "references/api-docs.md")`
+```
+
+### 4. 测试
+
+开启新会话并测试你的 skill：
+
+```bash
+hermes chat -q "/my-skill help me with the thing"
+```
+
+Skill 会自动出现——无需注册。放入 `~/.hermes/skills/` 即可立即生效。
+
+:::info
+Agent 也可以使用 `skill_manage` 自行创建和更新 skills。解决复杂问题后，Hermes 可能会主动提议将该方法保存为 skill，以便下次使用。
+:::
+
+---
+
+## 按平台管理 Skills
+
+控制哪些 skills 在哪些平台上可用：
+
+```bash
+hermes skills
+```
+
+这会打开一个交互式 TUI，你可以按平台（CLI、Telegram、Discord 等）启用或禁用 skills。当你希望某些 skills 仅在特定场景下可用时非常有用——例如，在 Telegram 上禁用开发类 skills。
+
+---
+
+## Skills 与 Memory 的区别
+
+两者都跨会话持久化，但用途不同：
+
+| | Skills | Memory |
+|---|---|---|
+| **内容** | 程序性知识——如何做事 | 事实性知识——事物是什么 |
+| **时机** | 按需加载，仅在相关时加载 | 自动注入每个会话 |
+| **大小** | 可以较大（数百行） | 应保持紧凑（仅关键事实） |
+| **开销** | 加载前零 tokens | 少量但持续的 token 开销 |
+| **示例** | "如何部署到 Kubernetes" | "用户偏好深色模式，位于 PST 时区" |
+| **创建者** | 你、agent 或从 Hub 安装 | Agent，基于对话内容 |
+
+**经验法则：** 如果你会把它写进参考文档，它就是 skill；如果你会把它写在便利贴上，它就是 memory。
+
+---
+
+## 使用技巧
+
+**保持 skills 聚焦。** 试图涵盖"所有 DevOps"的 skill 会过于冗长且模糊。专注于"将 Python 应用部署到 Fly.io"的 skill 才足够具体，真正有用。
+
+**让 agent 创建 skills。** 完成复杂的多步骤任务后，Hermes 通常会主动提议将该方法保存为 skill。接受它——这些由 agent 编写的 skills 会捕捉到完整的工作流程，包括过程中发现的各种坑。
+
+**使用分类目录。** 将 skills 整理到子目录中（`~/.hermes/skills/devops/`、`~/.hermes/skills/research/` 等），保持列表整洁，并帮助 agent 更快找到相关 skills。
+
+**及时更新过时的 skills。** 如果使用某个 skill 时遇到它未覆盖的问题，告诉 Hermes 用你学到的内容更新该 skill。不维护的 skills 会成为负担。
+
+---
+
+*完整的 skills 参考——frontmatter 字段、条件激活、外部目录等——请见 [Skills 系统](/user-guide/features/skills)。*