第5章 提示词与技能 · Omnigent
提示词与技能
代理的行为由系统提示词决定。技能通过提供可复用的指令集来扩展其功能，代理可随需加载这些指令集。
系统提示词
你可以使用 prompt 或 instructions 来设置代理的系统提示词。两者均支持内联文本；instructions 还可接受文件路径。
# 内联文本（任选其一字段）： prompt: 你是一个简洁的编码助手。
# 等价写法： instructions: 你是一个简洁的编码助手。
# 从文件加载（仅限 instructions）： instructions: prompts/system.md
instructions 还接受文件路径（相对于代理 YAML 所在目录解析）。若同时设置两个字段，以 instructions 为准。
自动发现
当 prompt 和 instructions 均未设置时，Omnigent 会按以下顺序扫描代理目录中的上下文文件：
AGENTS.md CLAUDE.md .cursorrules
找到的第一个文件将作为系统提示词。不进行合并，以首个为准。
技能
技能是可复用的指令包，代理可通过 /skill-name 斜杠命令或内置的 load_skill 工具在运行时加载。每个技能是一个包含结构化指令的 Markdown 文件。你可以将其视为代理执行特定任务时遵循的“配方”。
技能的发现方式
Omnigent 从两个来源发现技能：
1. 随代理一同发布的捆绑技能： my-agent/ config.yaml skills/ code-review/ SKILL.md deploy/ SKILL.md
位于代理 skills/ 目录下的技能始终可用。代理可通过斜杠命令（如 /code-review）调用任一技能，或将其加载到 load_skill 中。
2. 项目和用户技能，从文件系统中发现： Omnigent 从代理工作目录开始，沿目录树向上查找每一级下的 .agents/skills/ 和 .claude/skills/ 目录，同时也查找主目录下的全局技能：
此机制类似于 .gitignore。只需在项目中放入一个技能文件夹，即可被所有代理自动拾取。
现有的 Claude Code 技能
若你的 .claude/skills/ 中已有技能，它们可自动与 Omnigent 捆绑技能共同使用。Omnigent 在目录遍历过程中会发现这些技能。 但有一点需要注意：Omnigent 的技能加载器仅从 SKILL.md 的 frontmatter 中读取 name、description 和 user-invocable。Claude Code 中额外的 frontmatter 字段则由不同的 harness 处理方式而定： Frontmatter 字段 | Omnigent 技能加载器 | claude-native harness name | 解析 | 解析 description | 解析 | 解析 user-invocable | 解析 | 解析 disable-model-invocation | 忽略 | 受支持 allowed-tools | 忽略 | 受支持 若你需要使用 disable-model-invocation 或 allowed-tools 行为，请改用 claude-native harness，并将这些技能放入 .claude/skills/ 目录。
现有的 Codex 技能和插件 在 Codex 的 harness（codex 和 codex-native）中，Omnigent 还会展示 Codex 本身已知的技能，使它们与捆绑技能和发现技能一同出现在技能菜单中：
- Codex 家目录下 skills/ 中的独立 Codex 技能。这些技能按目录名列出（即 Codex 注册的斜杠命令名），而非按 frontmatter 中的名称列出。 - 已安装 Codex 插件中的技能。Omnigent 使用会话的 Codex 家目录执行 codex plugin list --json，从每个已安装且启用的插件中加载技能，并读取 Codex 插件缓存中清单报告的精确版本。已禁用的插件和过期的缓存版本会被隐藏；在 Codex 中更新插件后，下一次发现时 Omnigent 的列表随之变化。
插件技能采用
一些实践性说明： - codex-native 会话使用会话的 Codex 家目录；基于进程的 codex（SDK）harness 使用 ~/.codex。 - 插件发现需要 agent 所在机器上安装 Codex CLI。若 CLI 缺失、超时（5秒）或返回无法解析的内容，插件技能将被省略——独立 Codex 技能及其他功能正常运行。 - manifest 损坏或 SKILL.md 无法读取的插件会被跳过，日志中显示警告；其他插件不受影响。 - 在 skills: none 设置下，Omnigent 绝不查询插件清单。
SKILL.md 格式 每个技能都拥有自己的独立文件夹，并必须包含一个带有 YAML frontmatter 的 SKILL.md 文件： skills/ my-skill/ SKILL.md references/ # 可选资源文件 style-guide.md scripts/ # 可选脚本 assets/ # 可选资源
SKILL.md 文件包含两个部分：YAML frontmatter 和 Markdown 正文。
--- name: code-review description: >- 从正确性、测试、安全性和可维护性方面审查代码变更。当被要求审查 PR 或 diff 时使用。 ---
代码审查
## 流程 1. 仔细审阅 diff。 2. 检查正确性及边界情况。 3. 确保测试覆盖相关变更。 4. 标记安全隐患。 5. 将发现结果汇总为：阻塞性问题 / 非阻塞性问题 / 建议。
## 审查要点 - 差一错误 - 缺失的错误处理 - 未测试的分支 ...
必填 frontmatter 字段： 字段 | 描述 name | 唯一技能标识符。用于斜杠命令（/code-review）和 load_skill 调用中。 description | 单行描述。展示给代理，以便其知晓何时使用此技能。
frontmatter 之后的 Markdown 正文即完整的指令集。其长度和详细程度不限。
资源文件 技能可以在 references/、scripts/ 和 assets/ 子目录中携带参考材料。加载技能时，代理将看到可用的文件列表，并通过 read_skill_file 工具读取它们： skills/ deploy/ SKILL.md references/ runbook.md checklist.md scripts/ validate.sh
示例：Polly 的技能 Polly 编排器捆绑了三个定义其工作流的技能： examples/polly/ config.yaml skills/ investigate/ SKILL.md # 只读调查工作流 fanout/ SKILL.md # 并行任务分派 cross-review/ SKILL.md # 跨厂商 PR 审查
每个技能定义了编排器遵循的分步流程。例如，investigate 技能指示 Polly 将问题拆解为有限任务、分派子代理并综合其报告。
过滤发现技能 默认情况下，加载所有项目和用户技能（skills: all）。你可以在代理 YAML 中限制此行为： # 加载所有发现技能（默认）： skills: all
# 不加载发现技能（完全隔离）： skills: none
# 仅按名称加载特定的发现技能： skills: - code-review - deploy
此设置仅影响发现技能（来自 .agents/skills/ 和 .claude/skills/，在 Codex harness 上还包括独立 Codex 技能和 Codex 插件技能）。位于代理自身 skills/ 目录下的捆绑技能始终可用，不受影响。 对于 Codex 插件技能，列表项既可匹配裸技能名称，也可匹配命名空间格式。因此，review 和 toolkit:review 均可选中 toolkit:review。裸名称将从所有提供该技能的已启用插件中选择它。
