AI 编程工具 Skill/Agent YAML Frontmatter 配置参考

涵盖 Claude Code、OpenAI Codex、OpenCode、OpenClaw、pi-mono、Hermes Agent 六款主流工具

一、通用标准（AgentSkills 规范）

所有工具都遵循 agentskills.io 开放标准的基础字段：

yaml

---
name: skill-name           # 必需: 1-64字符，小写字母+数字+连字符
description: Description   # 必需: 1-1024字符，用途+触发时机
license: MIT               # 可选: SPDX 许可证标识符
compatibility: Requires... # 可选: 环境要求（max 500字符）
metadata:                  # 可选: 扩展元数据对象
  custom_key: value
---

字段约束

字段	约束
`name`	1-64字符，`^[a-z0-9]+(-[a-z0-9]+)*$`，匹配目录名
`description`	1-1024字符，应包含用途和触发关键词
`license`	SPDX 格式，如 `MIT`, `Apache-2.0`
`compatibility`	环境要求说明，如 `Requires Python 3.14+`
`metadata`	任意键值对，建议用唯一前缀避免冲突

二、共同特性（六款工具共有）

2.1 基础元数据

字段	说明	示例
`name`	Skill 唯一标识符	`code-review`, `deploy-check`
`description`	功能描述和触发时机	`Review code for quality issues`
`license`	许可证声明	`MIT`, `Apache-2.0`
`compatibility`	环境兼容性说明	`Requires Node.js 18+`
`metadata`	扩展元数据对象	`{ author: "team" }`

2.2 调用控制

字段	支持工具	说明
`disable-model-invocation`	Claude Code, pi-mono	阻止模型自动调用，仅用户可触发
`user-invocable`	Claude Code	控制是否显示在菜单中
`allowed-tools`	Claude Code, Codex, pi-mono	预授权工具列表

2.3 工具控制

字段	支持工具	格式
`allowed-tools`	Claude Code, Codex	`"Read Grep Bash(git:*))"` 或 YAML 列表
`tools`	OpenCode	`{ read: true, write: false }`
`tools`	pi-mono	`"bash,read,write"`（逗号分隔）

三、单独特性（按工具分类）

3.1 Claude Code（执行控制最丰富）

yaml

---
name: code-review
description: Review code for quality issues

# ============ 触发控制 ============
when_to_use: "Trigger when user mentions 'review'"  # 补充触发词
argument-hint: [file-path]                           # 参数提示
disable-model-invocation: true                       # 阻止自动触发
user-invocable: false                                # 隐藏菜单

# ============ 执行控制 ============
allowed-tools: Read Grep Bash(git:*)
model: claude-opus-4                                 # 指定模型
effort: high                                         # 推理努力级别
context: fork                                        # fork=隔离子代理
agent: Explore                                       # 子代理类型

# ============ 范围限制 ============
paths:                                               # Glob 模式
  - "src/**/*.ts"
  - "tests/**/*.test.ts"

# ============ 生命周期钩子 ============
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"

# ============ Shell 指定 ============
shell: bash  # 或 powershell
---

特有字段清单：

字段	类型	说明
`when_to_use`	string	补充触发语境，追加到 description
`argument-hint`	string	自动补全时显示的参数提示，如 `[issue-number]`
`disable-model-invocation`	boolean	`true`=仅用户可调用，Claude 不会自动触发
`user-invocable`	boolean	`false`=从 `/` 菜单隐藏
`allowed-tools`	string/list	预授权工具，skill 激活时无需逐次批准
`model`	string	指定模型：`best`/`sonnet`/`opus`/`haiku` 或完整名称
`effort`	string	推理努力：`low`/`medium`/`high`/`xhigh`/`max`
`context`	string	`fork`=在隔离子代理中运行
`agent`	string	子代理类型：`Explore`/`Plan`/`Oracle`
`hooks`	object	生命周期钩子绑定：`PreToolUse`/`Stop` 等
`paths`	string/list	Glob 模式，仅操作匹配文件时自动加载
`shell`	string	`bash` 或 `powershell`

3.2 OpenAI Codex（双层配置架构）

yaml

---
# SKILL.md - AgentSkills 标准层
name: pdf-processing
description: Extract PDF text, fill forms
license: Apache-2.0
compatibility: Requires Python 3.14+
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---

yaml

# agents/openai.yaml - 产品特定扩展层
interface:
  display_name: "PDF Processor"           # UI 显示名称
  short_description: "Process PDFs"       # UI 简短描述（25-64字符）
  icon_small: "./assets/small-400px.png"  # 小图标路径
  icon_large: "./assets/large-logo.svg"   # 大图标路径
  brand_color: "#3B82F6"                  # 品牌色
  default_prompt: "Process $skill-name"   # 默认提示片段

policy:
  allow_implicit_invocation: false        # 是否允许隐式调用

dependencies:
  tools:
    - type: "mcp"                         # MCP 依赖声明
      value: "github"
      description: "GitHub MCP server"
      transport: "streamable_http"
      url: "https://api.githubcopilot.com/mcp/"

特有设计：

特性	说明
双层配置	SKILL.md（标准）+ `agents/openai.yaml`（产品扩展）
UI 元数据	`interface.*` 字段控制图标、品牌色、显示名称
隐式调用控制	`policy.allow_implicit_invocation` 控制自动触发
MCP 依赖	`dependencies.tools[]` 预声明 MCP 服务器依赖

3.3 OpenCode（Agent 级细粒度控制）

yaml

---
# Skill Frontmatter
name: github-triage
description: GitHub triage for issues and PRs
license: MIT
compatibility: opencode
---

yaml

---
# Agent Frontmatter（扩展配置）
description: Code review agent
mode: subagent                    # primary | subagent | all
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1                  # 0-2
top_p: 0.9                        # 0-1
variant: high                     # max | high | medium | low | xhigh

# 工具控制
tools:
  write: false
  edit: false
  bash: true

# 权限控制
permission:
  edit: deny                      # ask | allow | deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
  webfetch: deny

# 其他
category: quick                   # 继承 category 配置
skills: [git-helper]              # 注入的 skill
disable: false                    # 禁用 agent
color: "#3B82F6"                  # UI 颜色
maxTokens: 4096                   # 最大响应 token
thinking:                         # Anthropic 扩展思考
  type: enabled
  budgetTokens: 200000
reasoningEffort: high             # OpenAI 推理强度
textVerbosity: medium             # 文本冗长度
hidden: false                     # 隐藏 from @ autocomplete
---

特有字段清单：

字段	类型	说明
`mode`	string	Agent 模式：`primary`/`subagent`/`all`
`temperature`	number	采样温度 0-2
`top_p`	number	Top-p 采样 0-1
`tools`	object	`{ toolName: boolean }` 启用/禁用工具
`permission`	object	细粒度权限：`ask`/`allow`/`deny`
`category`	string	继承 category 的模型和设置
`skills`	array	注入到 agent 的 skill 名称列表
`variant`	string	模型变体：`max`/`high`/`medium`/`low`/`xhigh`
`maxTokens`	number	最大响应 token 数
`thinking`	object	Anthropic 扩展思考配置
`reasoningEffort`	string	OpenAI 推理强度
`textVerbosity`	string	文本冗长度：`low`/`medium`/`high`
`color`	string	UI 颜色（hex 或主题色名）
`hidden`	boolean	从 @ autocomplete 隐藏

3.4 OpenClaw（企业级部署）

yaml

---
name: github
description: GitHub operations via gh CLI
homepage: https://cli.github.com
user-invocable: true

# OpenClaw 特有扩展
metadata:
  openclaw:
    always: true                    # 总是包含，跳过 gates
    emoji: "🐙"                      # UI emoji
    skillKey: "gh-cli"              # 自定义配置键
    primaryEnv: "GITHUB_TOKEN"      # API key 关联的环境变量
    
    # 平台过滤
    os: ["darwin", "linux", "win32"]
    
    # 依赖检查
    requires:
      bins: ["gh"]                  # 必需在 PATH
      anyBins: ["python", "node"]   # 至少一个在 PATH
      env: ["GITHUB_TOKEN"]         # 必需环境变量
      config: ["github.enabled"]    # 必需配置项（truthy）
    
    # 自动安装器
    install:
      - id: brew
        kind: brew                  # brew | apt | node | go | uv | download
        formula: gh
        bins: ["gh"]
        label: "Install GitHub CLI (brew)"
        os: ["darwin"]
      - id: apt
        kind: apt
        package: gh
        bins: ["gh"]
        label: "Install GitHub CLI (apt)"
        os: ["linux"]
      - kind: download
        url: "https://example.com/tool.tar.gz"
        archive: tar.gz
        extract: true
        stripComponents: 1
        targetDir: "~/.openclaw/tools/skillKey"
        bins: ["tool"]

# 命令 dispatch 控制
command-dispatch: tool              # 设为 tool 绕过 model
command-tool: skill_mcp             # 工具名称
command-arg-mode: raw               # raw=转发原始参数字符串
---

特有字段清单：

字段	类型	说明
`homepage`	string	UI 主页链接
`user-invocable`	boolean	是否作为 slash 命令暴露
`metadata.openclaw.always`	boolean	`true`=跳过所有 gates
`metadata.openclaw.emoji`	string	UI 显示的 emoji
`metadata.openclaw.skillKey`	string	自定义配置键名
`metadata.openclaw.primaryEnv`	string	与 `skills.entries.*.apiKey` 关联
`metadata.openclaw.os`	array	平台白名单：`darwin`/`linux`/`win32`
`metadata.openclaw.requires.bins`	array	必需在 PATH 的二进制
`metadata.openclaw.requires.anyBins`	array	至少一个在 PATH
`metadata.openclaw.requires.env`	array	必需环境变量
`metadata.openclaw.requires.config`	array	`openclaw.json` 中必须为 truthy 的路径
`metadata.openclaw.install[]`	array	安装器规格数组
`command-dispatch`	string	`tool`=绕过 model 直接 dispatch
`command-tool`	string	dispatch 时调用的工具名
`command-arg-mode`	string	`raw`=转发原始参数字符串

install 规格类型：

kind	必需字段	说明
`brew`	`formula`	Homebrew 安装
`apt`	`package`	APT 安装
`node`	`module`	npm 包安装
`go`	-	Go 工具安装
`uv`	-	uv 工具安装
`download`	`url`	下载并解压

3.5 pi-mono（简洁实用）

yaml

---
# Skill Frontmatter
name: gmail
description: Read and send Gmail via IMAP/SMTP
disable-model-invocation: false       # 禁止模型自动调用
---

yaml

---
# Agent Frontmatter（独立文件）
name: oracle
description: Quick verification agent
tools: bash,read,write,edit           # 逗号分隔工具列表
model: claude-sonnet-4-20250514       # 指定模型
---

yaml

---
# Prompt Template Frontmatter
description: Review PRs with structured analysis
argument-hint: "<PR-URL>"             # 参数提示
---

特有设计：

特性	说明
最简配置	仅核心字段，无复杂扩展
`disable-model-invocation`	控制是否参与自动发现
`tools`	逗号分隔字符串（`"bash,read,write"`）
`argument-hint`	Prompt Template 参数提示
通用解析器	支持任意扩展字段 `[key: string]: unknown`

3.6 Hermes Agent（条件激活与配置声明）

yaml

---
name: arxiv
description: Search academic papers from arXiv
version: 1.0.0                      # 版本号
author: Hermes Agent                # 作者
license: MIT

# 平台限制
platforms: [macos, linux]           # macos | linux | windows

# Hermes 扩展
metadata:
  hermes:
    tags: [Research, Arxiv]         # 搜索标签
    category: devops                # 类别
    related_skills: [ocr-skill]     # 相关 skill
    homepage: https://example.com
    
    # 条件激活
    requires_toolsets: [web]        # 需要这些 toolsets
    requires_tools: [web_search]    # 需要这些工具
    fallback_for_toolsets: [browser]  # 作为 fallback
    
    # 配置声明（用于 hermes config migrate）
    config:
      - key: myplugin.path
        description: "配置项描述"
        default: "default-value"
        prompt: "设置时的提示语"

# 环境依赖
required_environment_variables:
  - name: TENOR_API_KEY
    prompt: "Tenor API key"
    help: "Get at https://..."
    required_for: "GIF search"

required_credential_files:
  - path: google_token.json
    description: Google OAuth2 token
---

特有字段清单：

字段	类型	说明
`version`	string	版本号，如 `1.0.0`
`author`	string	作者名称
`platforms`	array	平台限制：`macos`/`linux`/`windows`
`metadata.hermes.tags`	array	搜索分类标签
`metadata.hermes.category`	string	类别名称
`metadata.hermes.related_skills`	array	相关 skill 引用
`metadata.hermes.requires_toolsets`	array	需要这些 toolsets 才显示
`metadata.hermes.requires_tools`	array	需要这些工具才显示
`metadata.hermes.fallback_for_toolsets`	array	当这些 toolsets 不可用时显示
`metadata.hermes.fallback_for_tools`	array	当这些工具不存在时显示
`metadata.hermes.config[]`	array	配置项声明，用于迁移工具
`required_environment_variables[]`	array	必需环境变量声明
`required_credential_files[]`	array	必需凭证文件声明

四、快速参考表

4.1 按功能分类

功能	推荐工具	关键字段
模型指定	Claude Code, OpenCode, pi-mono	`model`, `variant`
推理控制	Claude Code	`effort`, `reasoningEffort`
子代理	Claude Code, OpenCode	`context`, `agent`, `mode`
工具预授权	全部	`allowed-tools`, `tools`
权限控制	OpenCode	`permission`
路径范围	Claude Code	`paths`
生命周期钩子	Claude Code	`hooks`
平台过滤	OpenClaw, Hermes	`os`, `platforms`
依赖检查	OpenClaw, Hermes	`requires.`, `requires_`
自动安装	OpenClaw	`install[]`
UI 元数据	Codex, OpenClaw, Hermes	`interface.*`, `emoji`, `tags`
配置声明	Hermes	`config[]`
API Key 管理	OpenClaw	`primaryEnv`

4.2 字段支持矩阵

字段	CC	Codex	OC	OClaw	pi	Hermes
name	✅	✅	✅	✅	✅	✅
description	✅	✅	✅	✅	✅	✅
license	❌	✅	✅	✅	❌	✅
compatibility	❌	✅	✅	✅	❌	❌
metadata	✅	✅	✅	✅	✅	✅
version	❌	❌	❌	❌	❌	✅
author	❌	❌	❌	❌	❌	✅
when_to_use	✅	❌	❌	❌	❌	❌
argument-hint	✅	❌	❌	❌	✅	❌
disable-model-invocation	✅	❌	❌	✅	✅	❌
user-invocable	✅	❌	❌	✅	❌	❌
allowed-tools	✅	✅	❌	❌	✅	❌
tools	❌	❌	✅	❌	✅	❌
model	✅	❌	✅	❌	✅	❌
effort	✅	❌	❌	❌	❌	❌
context	✅	❌	❌	❌	❌	❌
agent	✅	❌	❌	❌	❌	❌
hooks	✅	❌	❌	❌	❌	❌
paths	✅	❌	❌	❌	❌	❌
shell	✅	❌	❌	❌	❌	❌
mode	❌	❌	✅	❌	❌	❌
temperature	❌	❌	✅	❌	❌	❌
permission	❌	❌	✅	❌	❌	❌
category	❌	❌	✅	❌	❌	❌
thinking	❌	❌	✅	❌	❌	❌
reasoningEffort	❌	❌	✅	❌	❌	❌
color	❌	❌	✅	❌	❌	❌
hidden	❌	❌	✅	❌	❌	❌
homepage	❌	❌	❌	✅	❌	❌
emoji	❌	❌	❌	✅	❌	✅
skillKey	❌	❌	❌	✅	❌	❌
primaryEnv	❌	❌	❌	✅	❌	❌
os	❌	❌	❌	✅	❌	❌
requires.*	❌	❌	❌	✅	❌	✅
install[]	❌	❌	❌	✅	❌	❌
command-dispatch	❌	❌	❌	✅	❌	❌
platforms	❌	❌	❌	❌	❌	✅
tags	❌	❌	❌	❌	❌	✅
requires_toolsets	❌	❌	❌	❌	❌	✅
fallback_for_*	❌	❌	❌	❌	❌	✅
config[]	❌	❌	❌	❌	❌	✅
required_environment_variables	❌	❌	❌	❌	❌	✅
required_credential_files	❌	❌	❌	❌	❌	✅

CC=Claude Code, OC=OpenCode, OClaw=OpenClaw, pi=pi-mono

五、最佳实践

5.1 跨工具兼容的 Skill

编写跨工具兼容的 skill 时，只使用 AgentSkills 标准字段：

yaml

---
name: my-skill
description: Brief description of what this skill does
license: MIT
metadata:
  author: your-name
  version: "1.0"
---

# Skill instructions here...

5.2 工具特定扩展

在 metadata 中使用工具前缀避免冲突：

yaml

metadata:
  # Claude Code 扩展
  claude:
    effort: high
  
  # OpenClaw 扩展
  openclaw:
    emoji: "🚀"
    requires:
      bins: ["node"]
  
  # Hermes 扩展
  hermes:
    tags: [DevOps, CI/CD]

5.3 YAML 解析注意事项

description 中的冒号：包含 : （冒号+空格）时必须加引号
yaml
```
# ❌ 错误
```

description: IMPORTANT: Must use anime style

✅ 正确

description: "IMPORTANT: Must use anime style"

或

description: "IMPORTANT - Must use anime style"


2. **metadata JSON 格式**：部分工具要求 metadata 为单行 JSON
```yaml
# OpenClaw 推荐格式
metadata: { "openclaw": { "emoji": "✨" } }

字符串引号：YAML 字符串值建议加引号避免解析歧义

六、参考资料

工具	官方文档
Claude Code	https://docs.anthropic.com/en/docs/claude-code/skills
OpenAI Codex	https://developers.openai.com/codex/skills
OpenCode	https://open-code.ai/docs/en/skills
OpenClaw	https://docs.openclaw.ai/tools/skills.md
pi-mono	https://github.com/badlogic/pi-mono
Hermes Agent	https://hermes-agent.nousresearch.com/docs/developer-guide/creating-skills/
AgentSkills 标准	https://agentskills.io/specification

文档生成时间：2026-04-20

AI 编程工具 Skill/Agent YAML Frontmatter 配置参考 ​

一、通用标准（AgentSkills 规范） ​

字段约束 ​

二、共同特性（六款工具共有） ​

2.1 基础元数据 ​

2.2 调用控制 ​

2.3 工具控制 ​

三、单独特性（按工具分类） ​

3.1 Claude Code（执行控制最丰富） ​

3.2 OpenAI Codex（双层配置架构） ​

3.3 OpenCode（Agent 级细粒度控制） ​

3.4 OpenClaw（企业级部署） ​

3.5 pi-mono（简洁实用） ​

3.6 Hermes Agent（条件激活与配置声明） ​

四、快速参考表 ​

4.1 按功能分类 ​

4.2 字段支持矩阵 ​

五、最佳实践 ​

5.1 跨工具兼容的 Skill ​

5.2 工具特定扩展 ​

5.3 YAML 解析注意事项 ​

✅ 正确 ​

或 ​

六、参考资料 ​

AI 编程工具 Skill/Agent YAML Frontmatter 配置参考

一、通用标准（AgentSkills 规范）

字段约束

二、共同特性（六款工具共有）

2.1 基础元数据

2.2 调用控制

2.3 工具控制

三、单独特性（按工具分类）

3.1 Claude Code（执行控制最丰富）

3.2 OpenAI Codex（双层配置架构）

3.3 OpenCode（Agent 级细粒度控制）

3.4 OpenClaw（企业级部署）

3.5 pi-mono（简洁实用）

3.6 Hermes Agent（条件激活与配置声明）

四、快速参考表

4.1 按功能分类

4.2 字段支持矩阵

五、最佳实践

5.1 跨工具兼容的 Skill

5.2 工具特定扩展

5.3 YAML 解析注意事项

✅ 正确

或

六、参考资料