agent 的 per-agent 运行时字段应该放 SKILL.md 的 metadata 还是独立 per-agent adapter【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills在 agent-skills 仓库里给某个具体 agentClaude Code、Gemini CLI、Antigravity添加模型路由、工具限制、轮次上限这类运行时字段时最常见的错误是直接把kind、model、temperature、max_turns、tools、context这些字段写进共享SKILL.md的顶层 frontmatter。项目对此有明确的裁决文档 docs/advanced-per-agent-configuration.md它是 per-agent 配置的唯一规范参考并明确取代了早期把厂商字段加到SKILL.md顶层 frontmatter的做法。这篇文章按该文档给出一套可执行的判断流程和放置位置。先给结论按字段类型分两类处理——厂商元数据model hints、routing tags 这类放SKILL.md的metadata键下运行时编排subagent 定义、turn limits、tool allowlists 这类放独立的 per-agent adapter 文件。顶层 frontmatter 只保留规范字段。第一步判断字段属于哪一类docs/advanced-per-agent-configuration.md 给出的归类表字段类型例子正确位置规范字段Spec fieldsname、description、license、compatibilitySKILL.md顶层 frontmatter厂商元数据Vendor metadatamodel hints、routing tagsSKILL.md中的metadata键下运行时编排Runtime orchestrationsubagent 定义、turn limits、tool allowlists独立的 per-agent adapter 文件判断依据是 Agent Skills 规范仓库内各 skill 均以此为准顶层 frontmatter 只保留name、description、license、compatibility、metadata外加实验性的allowed-tools。任何厂商或客户端特定的属性都不该出现在顶层。为什么不能图省事直接写顶层文档给出的理由是未知的顶层字段不保证会被忽略。很多解析器只读name和description、静默丢弃其余内容但严格的 spec-conformant 校验器或客户端可能直接标记或拒绝未识别的顶层键。把厂商字段收进metadata或拆出去文件在所有客户端上都能保持合规。放metadata键厂商元数据这一支如果字段只是 model hints、routing tags 这类元数据写进SKILL.mdfrontmatter 的metadata键下。此时顶层仍然只有规范字段文件保持可移植metadata内部放什么由目标 agent 决定规范本身不约束其内容。修改后可以用仓库自带的结构校验确认 frontmatter 仍然合法node scripts/validate-skills.js这是 docs/developer-onboarding.md 中 Tier 1 结构检查的入口规则实现在 scripts/lib/skill-lint.js。退出码 0 表示全部通过1 表示存在 error例如 frontmatter 缺少name/description、name与目录名不一致、description 超过 1024 字符等。放独立 adapter运行时编排这一支subagent 定义、max_turns、工具 allowlist 这类编排字段不该进SKILL.md而是写到各 agent 自己的资源文件里按目标 agent 走两条路径之一。路径 AGemini CLI / Antigravity —— subagent 定义文件subagent 定义放在.gemini/agents/*.md它们与 skill 是不同层级的资源。schema 是kindlocal或remote、model、temperature、max_turns、tools。文档特别强调这是 subagent schema不是 skill schema两者不应该合并进同一个SKILL.md。文档给出的示例原样引自 docs/advanced-per-agent-configuration.md# .gemini/agents/security-auditor.md --- kind: local model: gemini-3-pro thinking_level: high # not: temperature: 0.1 tools: [read_file, grep] max_turns: 10 ---两个要点工具限制tools列表按 subagent 实现最小权限同时把用不到的工具 schema 从 prompt 里裁掉max_turns用于防止失控的纠错循环。模型路由方面轻量任务格式化、文档、git 操作可以指到更快的模型把强模型留给调试、安全审计、接口设计这类认知负载高的工作。版本相关的限制Google 建议 Gemini 3.x 模型省略temperature、改用thinking_level。不要给路由到 3.x 模型的 skill 或 subagent 硬编码temperature模型演进后需要回头重看这条建议。路径 BClaude Code —— 本地命令/技能副本Claude Code 通过name和description发现 skill。自定义命令和 skill 共用同一套 frontmatter因此下面的字段在.claude/commands/*.md和.claude/skills/*/SKILL.md里都生效context: fork让命令或 skill 在隔离的 subagent 上下文里运行而不是当前会话。收益是上下文隔离、从干净状态可重复执行、执行 token 消耗在 fork 侧而非主会话且只有结果回传主会话。可选的agent字段指定 fork 由哪种 subagent 执行例如agent: Plan默认general-purpose。allowed-tools预批准工具不是限制。列出的工具在该轮免权限提示直接运行授权在你下一条消息时清除工具池不会被缩减。disallowed-tools真正做限制的字段——skill 激活期间把列出的工具从可用池里移除这是 review/audit 这类被动阶段做最小权限所需要的。限制同样在下一条消息时清除。关键边界disallowed-tools是 Claude Code 自有字段不在规范的六个字段之列所以它属于本地副本或 adapter 文件。写进要发布的共享SKILL.md会在打包时报 unexpected-key 错误。共享的、对外发布的SKILL.md应保持只含规范字段这些运行时控制放在你自己的本地命令或 skill 副本里。如何验证放对了位置文档支撑的验证方式有三条结构校验node scripts/validate-skills.js通过exit 0确认 frontmatter 仍是合法形态。打包失败信号如果发布版SKILL.md里混入了 Claude Code 特有字段如disallowed-tools打包会直接报 unexpected-key 错误——这是把编排字段写错位置最直接的报错现象看到它就该把字段挪到本地副本或 adapter。对照归类表自查顶层 frontmatter 只出现name、description、license、compatibility、metadata及实验性allowed-toolskind、model、temperature、max_turns、tools、context不出现在顶层。限制与常见误区Opt-in不是全局默认运行时控制应该由用户为自己的 agent 和工作流按需添加不要烘焙成仓库里每个 skill 的默认值。旧做法已废止把kind、model、temperature、max_turns、tools、context加到顶层 frontmatter 的方式被 docs/advanced-per-agent-configuration.md 明确取代如果你在别人的分支里见到这种写法按上文的归类表迁移。脚本化生成尚是提案文档描述的单一事实源 生成器方案元数据类字段自动注入metadata键、编排类字段生成.gemini/agents/*.md等 adapter并做语义校验而不只是形状校验目前仍标注为 pending agreement尚未实现。现阶段按文档手写metadata和 adapter 文件是默认路径。仓库内已发布的 skill如 skills/code-review-and-quality/SKILL.md都只保留了name和description顶层字段可直接对照它们确认什么算干净的共享 frontmatter格式规范见 docs/skill-anatomy.md。按这套流程操作完共享SKILL.md在 Claude Code、Cursor、Gemini CLI、Antigravity 等所有 spec-conformant 客户端上保持可移植而每个 agent 的运行时控制以 opt-in 的方式落在它自己的 adapter 或本地副本里——两边互不污染。【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考