Claude Code 插件开发

编写 Hermes-Agent Skills（仓库内）

概述

SKILL.md 可以放在两个位置：

1. 用户本地：~/.hermes/skills///SKILL.md — 个人使用，不共享。通过 skill_manage(action='create') 创建。
2. 仓库内（本技能讨论的情况）：/home/bb/hermes-agent/skills///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。硬性要求：

• 以 --- 作为文件开头（前面不能有空白行）。
• 在正文之前以 --- 结束。
• 可解析为 YAML 映射。
• 必须包含 name 字段。
• 必须包含 description 字段，且 ≤ 1024 字符（MAX_DESCRIPTION_LENGTH）。
• 结束 --- 之后正文不能为空。

skills/software-development/ 下所有技能共用的结构范式：

---
name: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
description: Use when . .
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [short, descriptive, tags]
    related_skills: [other-skill, another-skill]
---

version / author / license / metadata 不由验证器强制，但每个同类技能都有——省略会让你的技能显得突兀。

大小限制

• 描述：≤ 1024 字符（强制）。
• 完整 SKILL.md：≤ 100,000 字符（以 MAX_SKILL_CONTENT_CHARS 强制，约 3.6 万 tokens）。
• software-development/ 中的同类技能为 8-14k 字符。以这个范围为目标。如果超过 20k，拆分为 references/*.md 并从 SKILL.md 引用。

对齐同类结构

每个仓库内技能大致遵循：

# 

并非每个章节都必需，但 Overview + When to Use + 可执行的正文 + pitfalls 是让技能看起来像同类的底线。

目录放置

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

阅读 2-3 个同类 SKILL.md，以对齐语气和结构。

1. 检查验证器约束：如有疑问，查看 tools/skill_manager_tool.py。
2. 起草：用 write_file 写入 skills///SKILL.md。
3. 本地验证：

   import yaml, re, pathlib
   content = pathlib.Path("skills///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

4. Git add + commit：在当前分支上提交。
5. 注意：当前会话的技能加载器是有缓存的——skill_view / skills_list 在新会话之前看不到新技能。这是预期行为，不是 bug。

交叉引用其他技能

metadata.hermes.related_skills 在加载时合并两棵目录树（仓库内 skills/ 和 ~/.hermes/skills/）。你可以从仓库内技能引用用户本地技能，但其他全新克隆仓库的用户将无法解析它。仓库内技能之间最好只引用仓库内技能。如果某个被频繁引用的技能只存在于 ~/.hermes/skills/，考虑把它提升到仓库中。

编辑现有仓库内技能

• 小修小补（错别字、新增 pitfall、收紧触发条件）：skill_manage(action='patch', name=..., old_string=..., new_string=...) 对仓库内技能同样适用。
• 重大重写：用 write_file 重写整个 SKILL.md。skill_manage(action='edit') 也可以，但需要提供完整的全新内容。
• 添加辅助文件：用 write_file 写入 skills///references/.md、templates/ 或 scripts/。skill_manage(action='write_file') 也可以，并且会强制 references/templates/scripts/assets 子目录白名单。
• 始终提交你的编辑——仓库内技能是源码，不是运行时状态。

常见误区（Common Pitfalls）

1. 用 skill_manage(action='create') 创建仓库内技能。它会写入 ~/.hermes/skills/，而不是仓库目录树。仓库内创建请使用 write_file。

1. --- 前面有前导空白。验证器检查 content.startswith("---")；任何前导空行或 BOM 都会导致验证失败。

1. 描述过于笼统。同类技能的描述以「Use when ...」开头，描述的是*触发类别*，而不是某一个任务。「Use when debugging X」优于「Debug X」。

1. 忘记 author/license/metadata 块。虽不由验证器强制，但每个同类都有；省略会让技能看起来像半成品。

1. 写了一个与同类重复的技能。创建之前，先 ls skills// 并打开 2-3 个同类。优先扩展现有技能，而不是创建一个狭窄的兄弟技能。

1. 期望当前会话能看到新技能。它看不到。技能加载器在会话开始时初始化。请在新会话中验证，或使用精确路径通过 skill_view 验证。

1. 链接到仓库内不存在的技能。related_skills: [some-user-local-skill] 对你有用，但对其他克隆者会失效。优先只引用仓库内技能。

验证清单

• [ ] 文件位于 skills///SKILL.md（而不是 ~/.hermes/skills/）
• [ ] Frontmatter 从第 0 字节开始是 ---，并以 --- 结束
• [ ] 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
• [ ] related_skills 引用的技能在仓库内可解析（或明确允许用户本地）
• [ ] 已在目标分支完成 git add skills/// && git commit