title: “创建技能” description: “如何编写 Hermes Skill：目录结构、SKILL.md 规范、安全扫描与发布方式。”
创建技能
Skill 是 Hermes 中表达“可复用能力包”的主要方式。它通常由说明文档、脚本、可选资源文件和激活条件组成，适合封装工作流，而不是底层 API 集成。
应该做成 Skill 还是 Tool？
优先做成 Skill 的场景：
- 能力主要由提示词说明驱动；
- 可以通过 shell 命令和现有工具完成；
- 不需要复杂的二进制处理或长连接；
- 更像“工作流程模板”而不是独立系统能力。
适合做成 Tool 的场景则包括：需要新 API 集成、独立 schema、复杂 I/O 或流式处理。
Skill 目录结构
一个典型 Skill 目录通常包含：
SKILL.md：必需，主说明文件；scripts/：可选，辅助脚本；assets/或模板文件：可选；- 配置或说明性资源文件：按需添加。
SKILL.md 格式
SKILL.md 是 Skill 的核心入口，通常需要描述：
- 这个技能在什么场景下使用；
- 快速参考；
- 推荐流程；
- 常见坑；
- 验证方式；
- 依赖的环境变量或文件。
# Skill Title
## When to Use
## Quick Reference
## Procedure
## Pitfalls
## Verification
平台特定 Skill
如果技能只适用于某些平台，应在文档中明确标注，并在运行时配置中配合启用/禁用。
条件激活
有些技能只在特定目录、特定文件存在或特定环境变量可用时才应启用。这类条件要写清楚，避免模型在无效上下文中使用技能。
环境变量要求
如果技能依赖密钥、认证文件或外部服务地址，应在 SKILL.md 中明确要求，并说明缺失时的退化行为。
加载时的安全设置
Skill 是可安装内容，因此安全边界很重要。
配置项（config.yaml）
技能系统通常允许对加载、启用状态和安全检查做配置。新增技能时要确保它不会绕过现有的启用/禁用机制。
凭证文件要求
如果技能依赖 OAuth token 或其他认证文件，应该说明：
- 文件放置位置；
- 最小权限要求；
- 缺失时的行为；
- 不要把这些文件硬编码进技能仓库。
Skill 编写准则
不引入外部依赖
能复用现有工具和内置命令时，不要为了一个 Skill 再增加额外安装步骤。Skill 越轻量，越容易分发与维护。
渐进披露
SKILL.md 应先给模型最关键的入口信息，再在需要时提供细节，而不是把一大段冗长背景一次性塞进去。
包含辅助脚本
如果某个流程很长、命令很复杂或输出需要标准化，建议把它放进 scripts/，而不是让模型每次临时现拼。
测试它
一个 Skill 至少应验证：
- 模型能正确识别何时使用；
- 脚本或命令可执行；
- 输出格式稳定；
- 缺失依赖时有可理解的报错。
Skill 应该放在哪里？
常见放置位置：
- 仓库内置
skills/：随项目分发； optional-skills/：官方可选内容；- 自定义技能仓库：团队或个人维护。
发布 Skill
发布到 Skills Hub
适合希望被更多用户直接安装和发现的通用技能。
发布到自定义仓库
适合团队私有技能、行业专用技能或实验性能力。
安全扫描
安装和加载技能时，系统会做一定的安全检查。技能作者应避免：
- 隐藏式执行高风险命令；
- 在文档中夹带越权指令；
- 引导模型读取不必要的敏感文件；
- 将秘密信息写死在仓库中。