@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/social-media/xurl/SKILL.md

@@ -0,0 +1,429 @@
+---
+name: xurl
+description: "通过 xurl CLI 使用 X/Twitter：发布、搜索、私信、媒体、v2 API。"
+version: 1.1.1
+author: xdevplatform + openclaw + Hermes Agent
+license: MIT
+platforms: [linux, macos]
+prerequisites:
+  commands: [xurl]
+metadata:
+  hermes:
+    tags: [twitter, x, social-media, xurl, official-api]
+    homepage: https://github.com/xdevplatform/xurl
+    upstream_skill: https://github.com/openclaw/openclaw/blob/main/skills/xurl/SKILL.md
+---
+
+# xurl — 通过官方 CLI 使用 X (Twitter) API
+
+`xurl` 是 X 开发者平台的官方 X API CLI。它支持常见操作的快捷命令，并且可以通过原始的 curl 风格访问任何 v2 endpoint。所有命令都会将 JSON 返回到 stdout。
+
+此 skill 用于：
+- 发布、回复、引用、删除帖子
+- 搜索帖子以及阅读时间线/提及
+- 点赞、转发、收藏
+- 关注、取关、拉黑、屏蔽
+- 私信
+- 上传媒体（图片和视频）
+- 原始访问任何 X API v2 endpoint
+- 多应用 / 多账户工作流
+
+这个 skill 替代了旧版的 `xitter` skill（后者封装了第三方的 Python CLI）。`xurl` 由 X 开发者平台团队维护，支持带有自动刷新功能的 OAuth 2.0 PKCE，并且覆盖了更广泛的 API 接口范围。
+
+---
+
+## 密钥安全（强制要求）
+
+在 agent/LLM 会话中操作时的关键规则：
+
+- **绝不**读取、打印、解析、总结、上传或将 `~/.xurl` 发送到 LLM 上下文中。
+- **绝不**要求用户将凭证/令牌粘贴到聊天中。
+- 用户必须在自己的机器上手动使用密钥填充 `~/.xurl`。在 Docker 中，这必须是 Hermes 工具子进程所能看到的 `~`；请参阅下文的 Docker 说明。
+- **绝不**在 agent 会话中推荐或执行带有内联密钥的授权命令。
+- **绝不**在 agent 会话中使用 `--verbose` / `-v` —— 它可能会暴露授权标头/令牌。
+- 要验证凭证是否存在，只能使用：`xurl auth status`。
+
+agent 命令中禁止使用的标志（它们接受内联密钥）：
+`--bearer-token`, `--consumer-key`, `--consumer-secret`, `--access-token`, `--token-secret`, `--client-id`, `--client-secret`
+
+应用凭证注册和凭证轮换必须由用户在 agent 会话之外手动完成。凭证注册完成后，用户需通过 `xurl auth oauth2` 进行授权 —— 同样要在 agent 会话之外进行。令牌会以 YAML 格式持久化到 `~/.xurl`。每个应用都有独立的令牌。OAuth 2.0 令牌会自动刷新。
+
+---
+
+## 安装
+
+选择一种方法。在 Linux 上，使用 shell 脚本或 `go install` 最为简单。
+
+```bash
+# Shell 脚本（安装到 ~/.local/bin，无需 sudo，适用于 Linux + macOS）
+curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash
+
+# Homebrew (macOS)
+brew install --cask xdevplatform/tap/xurl
+
+# npm
+npm install -g @xdevplatform/xurl
+
+# Go
+go install github.com/xdevplatform/xurl@latest
+```
+
+验证：
+
+```bash
+xurl --help
+xurl auth status
+```
+
+如果 `xurl` 已安装，但 `auth status` 没有显示任何应用或令牌，用户需要手动完成授权 —— 请参阅下一节。
+
+---
+
+## 一次性用户配置（用户在 agent 之外运行这些步骤）
+
+这些步骤必须由用户直接执行，而不是由 agent 执行，因为它们涉及粘贴密钥。引导用户查看此区块；不要替他们执行。
+
+1. 在 https://developer.x.com/en/portal/dashboard 创建或打开一个应用
+2. 将 redirect URI 设置为 `http://localhost:8080/callback`
+3. 复制应用的 Client ID 和 Client Secret
+4. 在本地注册该应用（用户运行此命令）：
+   ```bash
+   xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
+   ```
+5. 授权（指定 `--app` 将令牌绑定到你的应用）：
+   ```bash
+   xurl auth oauth2 --app my-app
+   ```
+   （这将打开浏览器进行 OAuth 2.0 PKCE 流程。）
+
+   如果 X 在 OAuth 流程后的 `/2/users/me` 查询中返回 `UsernameNotFound` 错误或 403，请显式传入你的用户名（xurl v1.1.0+）：
+   ```bash
+   xurl auth oauth2 --app my-app YOUR_USERNAME
+   ```
+   这会将令牌绑定到你的用户名，并跳过出错的 `/2/users/me` 调用。
+6. 将该应用设为默认，以便所有命令都使用它：
+   ```bash
+   xurl auth default my-app
+   ```
+7. 验证：
+   ```bash
+   xurl auth status
+   xurl whoami
+   ```
+
+完成此操作后，agent 就可以使用下方的任何命令，无需进一步设置。OAuth 2.0 令牌会自动刷新。
+
+> **常见陷阱：** 如果你在 `xurl auth oauth2` 中省略了 `--app my-app`，OAuth 令牌将被保存到内置的 `default` 应用配置中 —— 该配置没有 client-id 或 client-secret。即使 OAuth 流程看似成功，命令也会因授权错误而失败。如果遇到这种情况，请重新运行 `xurl auth oauth2 --app my-app` 和 `xurl auth default my-app`。
+
+> **Docker HOME 陷阱：** 在官方的 Hermes Docker 布局中，`/opt/data` 是 `HERMES_HOME`，但 Hermes 工具子进程使用 `/opt/data/home` 作为 `HOME`。这意味着对于 Hermes 运行的 `xurl` 命令，`~/.xurl` 会解析为 `/opt/data/home/.xurl`，而不是 `/opt/data/.xurl`。请使用相同的 HOME 运行用户设置：
+> ```bash
+> HOME=/opt/data/home xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
+> HOME=/opt/data/home xurl auth oauth2 --app my-app YOUR_USERNAME
+> HOME=/opt/data/home xurl auth default my-app YOUR_USERNAME
+> HOME=/opt/data/home xurl auth status
+> ```
+> 如果 `HOME=/opt/data xurl auth status` 成功，但 `HOME=/opt/data/home xurl auth status` 未显示任何应用或令牌，则 Hermes 工具调用将无法看到凭证。
+
+---
+
+## 快速参考
+
+| 操作 | 命令 |
+| --- | --- |
+| 发布 | `xurl post "Hello world!"` |
+| 回复 | `xurl reply POST_ID "Nice post!"` |
+| 引用 | `xurl quote POST_ID "My take"` |
+| 删除帖子 | `xurl delete POST_ID` |
+| 读取帖子 | `xurl read POST_ID` |
+| 搜索帖子 | `xurl search "QUERY" -n 10` |
+| 我是谁 | `xurl whoami` |
+| 查找用户 | `xurl user @handle` |
+| 主页时间线 | `xurl timeline -n 20` |
+| 提及 | `xurl mentions -n 10` |
+| 点赞 / 取消点赞 | `xurl like POST_ID` / `xurl unlike POST_ID` |
+| 转发 / 撤销 | `xurl repost POST_ID` / `xurl unrepost POST_ID` |
+| 收藏 / 移除 | `xurl bookmark POST_ID` / `xurl unbookmark POST_ID` |
+| 列出收藏 / 点赞 | `xurl bookmarks -n 10` / `xurl likes -n 10` |
+| 关注 / 取关 | `xurl follow @handle` / `xurl unfollow @handle` |
+| 正在关注 / 关注者 | `xurl following -n 20` / `xurl followers -n 20` |
+| 拉黑 / 取消拉黑 | `xurl block @handle` / `xurl unblock @handle` |
+| 屏蔽 / 取消屏蔽 | `xurl mute @handle` / `xurl unmute @handle` |
+| 发送私信 | `xurl dm @handle "message"` |
+| 列出私信 | `xurl dms -n 10` |
+| 上传媒体 | `xurl media upload path/to/file.mp4` |
+| 媒体状态 | `xurl media status MEDIA_ID` |
+| 列出应用 | `xurl auth apps list` |
+| 移除应用 | `xurl auth apps remove NAME` |
+| 设置默认应用 | `xurl auth default APP_NAME [USERNAME]` |
+| 指定请求应用 | `xurl --app NAME /2/users/me` |
+| 授权状态 | `xurl auth status` |
+
+说明:
+- `POST_ID` 也接受完整的 URL（例如 `https://x.com/user/status/1234567890`）—— xurl 会自动提取 ID。
+- 用户名带不带前导 `@` 均可。
+
+---
+
+## 命令详情
+
+### 发布
+
+```bash
+xurl post "Hello world!"
+xurl post "Check this out" --media-id MEDIA_ID
+xurl post "Thread pics" --media-id 111 --media-id 222
+
+xurl reply 1234567890 "Great point!"
+xurl reply https://x.com/user/status/1234567890 "Agreed!"
+xurl reply 1234567890 "Look at this" --media-id MEDIA_ID
+
+xurl quote 1234567890 "Adding my thoughts"
+xurl delete 1234567890
+```
+
+### 阅读与搜索
+
+```bash
+xurl read 1234567890
+xurl read https://x.com/user/status/1234567890
+
+xurl search "golang"
+xurl search "from:elonmusk" -n 20
+xurl search "#buildinpublic lang:en" -n 15
+```
+
+对于 X Articles，请使用原始 API 模式而不是 `read` 快捷方式。`xurl read` 需要帖子 ID 或帖子 URL；不要将 `read` 放在 `/2/tweets/...` endpoint 之前。请求 `article` tweet 字段，并从 JSON 响应中提取 `data.article.plain_text`：
+
+```bash
+xurl --app APP_NAME '/2/tweets/2057909493250539891?expansions=author_id,attachments.media_keys,referenced_tweets.id&tweet.fields=created_at,lang,public_metrics,context_annotations,entities,possibly_sensitive,conversation_id,in_reply_to_user_id,referenced_tweets,article'
+```
+
+### 用户、时间线、提及
+
+```bash
+xurl whoami
+xurl user elonmusk
+xurl user @XDevelopers
+
+xurl timeline -n 25
+xurl mentions -n 20
+```
+
+### 互动
+
+```bash
+xurl like 1234567890
+xurl unlike 1234567890
+
+xurl repost 1234567890
+xurl unrepost 1234567890
+
+xurl bookmark 1234567890
+xurl unbookmark 1234567890
+
+xurl bookmarks -n 20
+xurl likes -n 20
+```
+
+### 社交关系图
+
+```bash
+xurl follow @XDevelopers
+xurl unfollow @XDevelopers
+
+xurl following -n 50
+xurl followers -n 50
+
+# 其他用户的关系图
+xurl following --of elonmusk -n 20
+xurl followers --of elonmusk -n 20
+
+xurl block @spammer
+xurl unblock @spammer
+xurl mute @annoying
+xurl unmute @annoying
+```
+
+### 私信
+
+```bash
+xurl dm @someuser "Hey, saw your post!"
+xurl dms -n 25
+```
+
+### 媒体上传
+
+```bash
+# 自动检测类型
+xurl media upload photo.jpg
+xurl media upload video.mp4
+
+# 显式指定类型/类别
+xurl media upload --media-type image/jpeg --category tweet_image photo.jpg
+
+# 视频需要服务器端处理 —— 检查状态（或轮询）
+xurl media status MEDIA_ID
+xurl media status --wait MEDIA_ID
+
+# 完整工作流
+xurl media upload meme.png                  # 返回媒体 ID
+xurl post "lol" --media-id MEDIA_ID
+```
+
+---
+
+## 原始 API 访问
+
+快捷方式涵盖了常见操作。对于其他任何操作，请针对任何 X API v2 endpoint 使用原始 curl 风格模式：
+
+```bash
+# GET
+xurl /2/users/me
+
+# 带 JSON body 的 POST
+xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
+
+# DELETE / PUT / PATCH
+xurl -X DELETE /2/tweets/1234567890
+
+# 自定义标头
+xurl -H "Content-Type: application/json" /2/some/endpoint
+
+# 强制流式传输
+xurl -s /2/tweets/search/stream
+
+# 也支持完整 URL
+xurl https://api.x.com/2/users/me
+```
+
+---
+
+## 全局标志
+
+| 标志 | 简写 | 说明 |
+| --- | --- | --- |
+| `--app` |  | 使用特定的已注册应用（覆盖默认设置） |
+| `--auth` |  | 强制授权类型：`oauth1`、`oauth2` 或 `app` |
+| `--username` | `-u` | 要使用的 OAuth2 账户（如果存在多个账户） |
+| `--verbose` | `-v` | **在 agent 会话中禁止使用** —— 会泄露授权标头 |
+| `--trace` | `-t` | 添加 `X-B3-Flags: 1` 追踪标头 |
+
+---
+
+## 流式传输
+
+流式传输 endpoint 会被自动检测。已知的包括：
+
+- `/2/tweets/search/stream`
+- `/2/tweets/sample/stream`
+- `/2/tweets/sample10/stream`
+
+使用 `-s` 可在任何 endpoint 上强制开启流式传输。
+
+---
+
+## 输出格式
+
+所有命令都会将 JSON 返回到 stdout。其结构映射了 X API v2：
+
+```json
+{ "data": { "id": "1234567890", "text": "Hello world!" } }
+```
+
+错误也是 JSON 格式：
+
+```json
+{ "errors": [ { "message": "Not authorized", "code": 403 } ] }
+```
+
+---
+
+## 常见工作流
+
+### 带图片发布
+```bash
+xurl media upload photo.jpg
+xurl post "Check out this photo!" --media-id MEDIA_ID
+```
+
+### 回复对话
+```bash
+xurl read https://x.com/user/status/1234567890
+xurl reply 1234567890 "Here are my thoughts..."
+```
+
+### 搜索与互动
+```bash
+xurl search "topic of interest" -n 10
+xurl like POST_ID_FROM_RESULTS
+xurl reply POST_ID_FROM_RESULTS "Great point!"
+```
+
+### 检查你的动态
+```bash
+xurl whoami
+xurl mentions -n 20
+xurl timeline -n 20
+```
+
+### 多应用（凭证已手动预配置）
+```bash
+xurl auth default prod alice               # prod 应用，alice 用户
+xurl --app staging /2/users/me             # 针对 staging 的一次性请求
+```
+
+---
+
+## 错误处理
+
+- 发生任何错误时返回非零退出码。
+- API 错误仍会作为 JSON 打印到 stdout，因此你可以对其进行解析。
+- 授权错误 → 请用户在 agent 会话之外重新运行 `xurl auth oauth2`。
+- 需要调用者用户 ID 的命令（如点赞、转发、收藏、关注等）将通过 `/2/users/me` 自动获取。如果在此处发生授权失败，将表现为授权错误。
+
+---
+
+## Agent 工作流
+
+1. 验证先决条件：`xurl --help` 和 `xurl auth status`。
+2. **检查默认应用是否包含凭证。** 解析 `auth status` 输出。默认应用标有 `▸`。如果默认应用显示 `oauth2: (none)`，而另一个应用拥有有效的 oauth2 用户，请告知用户运行 `xurl auth default <that-app>` 进行修复。这是最常见的设置错误 —— 用户添加了具有自定义名称的应用，但从未将其设为默认值，因此 xurl 会不断尝试使用空的 `default` 配置。
+3. 如果完全缺失授权，请停止操作并引导用户前往“一次性用户配置”部分 —— **不要**尝试自行注册应用或传递密钥。
+4. 从开销较低的读取操作（`xurl whoami`、`xurl user @handle`、`xurl search ... -n 3`）开始，以确认连通性。
+5. 在执行任何写入操作（发布、回复、点赞、转发、私信、关注、拉黑、删除）之前，确认目标帖子/用户以及用户的意图。
+6. 直接使用 JSON 输出 —— 每个响应都已结构化。
+7. 切勿将 `~/.xurl` 的内容粘贴回对话中。
+
+---
+
+## 故障排除
+
+| 症状 | 原因 | 修复方法 |
+| --- | --- | --- |
+| OAuth 流程成功后出现授权错误 | 令牌保存到了 `default` 应用（无 client-id/secret），而不是你命名的应用 | `xurl auth oauth2 --app my-app`，然后运行 `xurl auth default my-app` |
+| OAuth 期间出现 `unauthorized_client` | 在 X 仪表板中将应用类型设置为了 "Native App" | 在“用户授权设置”中更改为 "Web app, automated app or bot" |
+| OAuth 刚刚完成后，在 `/2/users/me` 上出现 `UsernameNotFound` 或 403 | X 无法可靠地从 `/2/users/me` 返回用户名 | 重新运行 `xurl auth oauth2 --app my-app YOUR_USERNAME`（xurl v1.1.0+）以显式传入用户名 |
+| 每个请求都出现 401 | 令牌过期或默认应用错误 | 检查 `xurl auth status` —— 验证 `▸` 是否指向具有 oauth2 令牌的应用 |
+| `client-forbidden` / `client-not-enrolled` | X 平台注册问题 | Dashboard（仪表板） -> Apps（应用） -> Manage（管理） -> 移至 "Pay-per-use" 套餐 -> Production（生产）环境 |
+| `CreditsDepleted` | X API 余额为 $0 | 在 Developer Console -> Billing（计费）中购买点数（最低 $5） |
+| 上传图片时出现 `media processing failed` | 默认类别为 `amplify_video` | 添加 `--category tweet_image --media-type image/png` |
+| X 仪表板中有两个 "Client Secret" 值 | UI 错误 —— 第一个实际上是 Client ID | 在 "Keys and tokens" 页面确认；ID 以 `MTpjaQ` 结尾 |
+
+---
+
+## 说明
+
+- **速率限制：** X 会对每个 endpoint 实施速率限制。返回 429 意味着需要等待并重试。写入 endpoint（发布、回复、点赞、转发）的限制比读取操作更严格。
+- **作用域：** OAuth 2.0 令牌使用宽泛的作用域。特定操作返回 403 通常意味着令牌缺少相应的作用域 —— 请让用户重新运行 `xurl auth oauth2`。
+- **令牌刷新：** OAuth 2.0 令牌会自动刷新。无需额外操作。
+- **多个应用：** 每个应用都有独立的凭证/令牌。使用 `xurl auth default` 或 `--app` 进行切换。
+- **每个应用有多个账户：** 使用 `-u / --username` 进行选择，或使用 `xurl auth default APP USER` 设置默认账户。
+- **令牌存储：** `~/.xurl` 是 YAML 格式。在 Docker 中，使用 Hermes 子进程的 HOME（官方镜像中为 `/opt/data/home`），以便将令牌存放在 `/opt/data/home/.xurl` 下。切勿读取此文件或将其发送到 LLM 上下文。
+- **成本：** X API 访问通常在实质性使用时需要付费。许多失败是由于套餐/权限问题，而不是代码问题。
+
+---
+
+## 来源说明
+
+- 上游 CLI：https://github.com/xdevplatform/xurl (X developer platform team, Chris Park et al.)
+- 上游 agent skill：https://github.com/openclaw/openclaw/blob/main/skills/xurl/SKILL.md
+- Hermes 适配：根据 Hermes skill 约定重新排版；安全防护措施原样保留。

package/extensions/skills/builtin/software-development/hermes-agent-skill-authoring/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: hermes-agent-skill-authoring
+description: "编写仓库内 SKILL.md：frontmatter、validator、结构和写作质量原则。"
+version: 1.1.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [skills, authoring, hermes-agent, conventions, skill-md]
+    related_skills: [plan, requesting-code-review]
+---
+
+# 编写 Hermes-Agent 技能（仓库内）
+
+## 概览
+
+SKILL.md 可以存放在两个位置：
+
+1. **用户本地：** `~/.hermes/skills/<maybe-category>/<name>/SKILL.md` — 个人使用，不共享。通过 `skill_manage(action='create')` 创建。
+2. **仓库内（本技能针对此情况）：** `/home/bb/hermes-agent/skills/<category>/<name>/SKILL.md` — 被提交并随包发布。使用 `write_file` + `git add`。`skill_manage(action='create')` 不针对此目录树。
+
+## 何时使用
+
+- 用户要求你“在此分支 / 仓库 / 提交中”添加技能
+- 你正在提交一个应随 hermes-agent 发布的可复用工作流
+- 你正在编辑 `/home/bb/hermes-agent/skills/` 下的现有技能（小修改使用 `patch`，重写使用 `write_file`；`skill_manage` 在仓库内技能上执行 `patch` 依然有效，但不支持 `create`）
+
+## 必需的 Frontmatter
+
+事实来源：`tools/skill_manager_tool.py::_validate_frontmatter`。硬性要求：
+
+- 以 `---` 作为起始字节开头（无前导空行）。
+- 在正文前以 `\n---\n` 结束。
+- 解析为 YAML 映射。
+- 包含 `name` 字段。
+- 包含 `description` 字段，≤ **1024 个字符**（`MAX_DESCRIPTION_LENGTH`）。
+- 结束的 `---` 后有非空正文。
+
+`skills/software-development/` 下每个技能使用的标准对齐格式：
+
+```yaml
+---
+name: my-skill-name               # 小写，连字符，≤64个字符 (MAX_NAME_LENGTH)
+description: Use when <trigger>. <one-line behavior>.
+version: 1.1.0
+author: Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: [short, descriptive, tags]
+    related_skills: [other-skill, another-skill]
+---
+```
+
+`version` / `author` / `license` / `metadata` 不受 validator 强制要求，但每个同类技能都包含它们——省略它们会让你的技能显得格格不入。
+
+## 大小限制
+
+- Description：≤ 1024 个字符（强制执行）。
+- 完整的 SKILL.md：≤ 100,000 个字符（作为 `MAX_SKILL_CONTENT_CHARS` 强制执行，约 36k tokens）。
+- `software-development/` 中的同类技能通常在 **8-14k 字符**之间。以此范围为目标。如果超过 20k，请拆分为 `references/*.md` 并在 SKILL.md 中引用它们。
+
+## 写作质量原则
+
+技能的存在是为了使 agent 的过程更加可预测。可预测性 **并不** 意味着每次运行产生相同的输出；它意味着 agent 可靠地遵循相同的有效规范。
+
+在编写或编辑任何技能时，请使用这些质量检查：
+
+1. **为过程可预测性进行优化。** 问问自己：加载此技能时应该改变什么行为？如果某一行不改变行为，就删掉它。
+2. **选择正确的 context 加载。** 模型调用的 Hermes 技能每轮都要为其 description 付出代价。保持 description 集中在触发类别和技能的独特行为上。将细节放在正文或链接的参考资料中。
+3. **使用信息层级。** 将始终需要的步骤放在 `SKILL.md` 中；将特定分支或庞大的参考资料放在 `references/`、`templates/` 或 `scripts/` 中，并仅在需要时指向它。
+4. **以完成标准结束步骤。** 每个有序步骤都应说明 agent 如何知道它已完成。好的标准是可检查的，并且在关键时要详尽无遗：“每个修改过的文件都已考虑到”胜过“总结修改”。
+5. **将规则与其管理的概念放在一起。** 避免将一个想法散布在文件各处。将定义、注意事项、示例和验证保持在彼此附近。
+6. **使用强有力的引导词。** 优先使用模型已经知道的紧凑概念——例如 "tight loop"、"tracer bullet"、"root cause"、"regression test"——而不是冗长的重复解释。一个好的引导词可以节省 tokens 并锚定行为。
+7. **剔除重复和无效操作。** 将每个含义保留在一个事实来源中。逐句询问该句是否改变了 agent 的默认行为。如果没有，删除它而不是润色它。
+8. **注意过早完成。** 如果 agent 倾向于匆忙完成某个步骤，首先锐化该步骤的完成标准。仅当后续步骤干扰了当前步骤的良好执行时，才拆分序列。
+
+常见的质量错误：
+
+- **过早完成** — 技能允许 agent 在工作真正完成之前继续下一步。
+- **重复** — 同一规则出现在多个地方并产生偏差。
+- **沉积** — 过时的行被保留下来，因为添加比删除感觉更安全。
+- **蔓延** — 过多始终可见的材料；将特定分支的参考资料推到指针后面。
+- **无效文本** — agent 在没有技能时就已经会遵循的通用建议。
+
+## 标准对齐结构
+
+每个仓库内的技能大致遵循：
+
+```
+# <Title>
+
+## Overview
+一两段话：是什么以及为什么。
+
+## When to Use
+- 项目符号形式的触发条件
+- "Don't use for:" 反向触发条件
+
+## <Topic sections specific to the skill>
+- 常见的快速参考表
+- 包含确切命令的代码块
+- 特定于 Hermes 的方案（通过 scripts/run_tests.sh 进行测试，ui-tui 路径等）
+
+## Common Pitfalls
+错误及其修复的编号列表。
+
+## Verification Checklist
+- [ ] 操作后验证的复选框列表
+
+## One-Shot Recipes (optional)
+命名的场景 → 具体命令序列。
+```
+
+并非每个部分都是强制性的，但 `Overview` + `When to Use` + 可操作的正文 + `Common Pitfalls` 是使技能看起来像同类技能的最低要求。
+
+## 目录放置
+
+```
+skills/<category>/<skill-name>/SKILL.md
+```
+
+仓库中当前的类别（通过 `ls skills/` 确认）：`autonomous-ai-agents`、`creative`、`data-science`、`devops`、`dogfood`、`email`、`gaming`、`github`、`leisure`、`mcp`、`media`、`mlops/*`、`note-taking`、`productivity`、`red-teaming`、`research`、`smart-home`、`social-media`、`software-development`。
+
+选择最接近的现有类别。不要随意发明新的顶级类别。
+
+## 工作流
+
+1. **调查目标类别中的同类技能：**
+   ```
+   ls skills/<category>/
+   ```
+   阅读 2-3 个同类 SKILL.md 文件以匹配语气和结构。
+2. **检查 validator 约束**（如果不确定），位于 `tools/skill_manager_tool.py`。
+3. **起草** 使用 `write_file` 写入 `skills/<category>/<name>/SKILL.md`。
+4. **本地验证：**
+   ```python
+   import yaml, re, pathlib
+   content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()
+   assert content.startswith("---")
+   m = re.search(r'\n---\s*\n', content[3:])
+   fm = yaml.safe_load(content[3:m.start()+3])
+   assert "name" in fm and "description" in fm
+   assert len(fm["description"]) <= 1024
+   assert len(content) <= 100_000
+   ```
+5. **Git add + commit** 在当前活动分支上。
+6. **注意：** 当前会话的技能加载器是缓存的 —— `skill_view` / `skills_list` 在新会话之前看不到新技能。这是预期行为，不是 bug。
+
+## 交叉引用其他技能
+
+`metadata.hermes.related_skills` 在加载时联合两个目录树（仓库内的 `skills/` 和 `~/.hermes/skills/`）。你可以在仓库内技能中引用用户本地技能，但对于全新 clone 该 repo 的其他用户来说，它无法解析。优先在仓库内技能中仅引用仓库内的其他技能。如果一个经常被引用的技能仅存在于 `~/.hermes/skills/` 中，请考虑将其提升到 repo 中。
+
+## 编辑现有的仓库内技能
+
+- **小修复（拼写错误、增加陷阱、收紧触发条件）：** `skill_manage(action='patch', name=..., old_string=..., new_string=...)` 在仓库内技能上运行良好。
+- **大幅重写：** 使用 `write_file` 重写整个 SKILL.md。`skill_manage(action='edit')` 也可用，但需要提供完整的新内容。
+- **添加辅助文件：** 使用 `write_file` 写入 `skills/<category>/<name>/references/<file>.md`、`templates/<file>` 或 `scripts/<file>`。`skill_manage(action='write_file')` 也可用，并强制执行 references/templates/scripts/assets 子目录白名单。
+- **始终提交** 编辑 —— 仓库内技能是源代码，而不是运行时状态。
+
+## 常见陷阱
+
+1. **对仓库内技能使用 `skill_manage(action='create')`。** 它会写入 `~/.hermes/skills/`，而不是仓库目录树。仓库内创建请使用 `write_file`。
+
+2. **`---` 之前有空白字符。** validator 检查 `content.startswith("---")`；任何前导空行或 BOM 都会导致验证失败。
+
+3. **Description 过于通用。** 同类技能的 description 以 "Use when ..." 开头，并描述*触发类别*，而不是单个任务。"Use when debugging X" > "Debug X"。
+
+4. **忘记 author/license/metadata 块。** 虽然不受 validator 强制要求，但每个同类技能都有；省略它会让技能看起来半途而废。
+
+5. **编写与同类技能重复的技能。** 创建之前，执行 `ls skills/<category>/` 并打开 2-3 个同类技能。优先扩展现有技能，而不是创建狭窄的同级技能。
+
+6. **期望当前会话能看到新技能。** 这不可能。技能加载器在会话开始时初始化。请在新的会话中或使用 `skill_view` 通过确切路径进行验证。
+
+7. **任由技能堆积沉积。** 技能应该随着时间的推移变得更短或更犀利。添加规则时，删除它所替换的旧措辞；不要永远叠加建议。
+
+8. **编写无效文本。** "Be careful"、"be thorough" 和 "use best practices" 很少改变模型行为。替换为可检查的完成标准或更强的引导词。
+
+9. **链接到仓库内不存在的技能。** `related_skills: [some-user-local-skill]` 对你有效，但对其他 clone 来说会失效。优先仅使用仓库内链接。
+
+## 验证 检查清单
+
+- [ ] 文件位于 `skills/<category>/<name>/SKILL.md`（不在 `~/.hermes/skills/` 中）
+- [ ] Frontmatter 从字节 0 开始，以 `---` 开头，以 `\n---\n` 结束
+- [ ] `name`、`description`、`version`、`author`、`license`、`metadata.hermes.{tags, related_skills}` 全部存在
+- [ ] Name ≤ 64 个字符，小写 + 连字符
+- [ ] Description ≤ 1024 个字符并以 "Use when ..." 开头
+- [ ] 文件总计 ≤ 100,000 个字符（目标为 8-15k）
+- [ ] 结构：`# Title` → `## Overview` → `## When to Use` → 正文 → `## Common Pitfalls` → `## Verification Checklist`
+- [ ] 每个有序步骤都有可检查的完成标准
+- [ ] Description 以触发条件为中心，避免与正文内容重复
+- [ ] 冗长或特定分支的参考资料在链接文件中逐步展示
+- [ ] 删除了无效文本和重复规则
+- [ ] `related_skills` 的引用在仓库内可解析（或明确允许为用户本地）
+- [ ] `git add skills/<category>/<name>/ && git commit` 已在预期分支上完成