OpenSRE 技能卡片契约主工作流 SKILL.md 的元数据 Schema、审计结论与发布校验【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensreOpenSRE 将「AI SRE Agent」的多步工作流沉淀为带 YAML frontmatter 的SKILL.md技能卡片本文以仓库根目录下的 SKILL_CONTRACT_REVIEW.md 为骨架完整还原这份主工作流契约的审计结论——包括九个保留技能与一个移除技能、四项运行时陈述修正、以及从 schema 到 CI 的双层校验机制并结合 schema.py、AGENTS.md、registry.py 等源码给出实现级佐证。读完本文你将掌握主工作流卡片允许的完整字段集与六元 metadata 的写法、菜单/包含/脚本工具等机制如何被严格校验、以及一次契约审计应当如何形成「可复现的核查结论」。一、审计背景与契约定义审计执行于 2026-09-12对象是core/agent_harness/prompts/skills/目录下全部主工作流main workflow卡片。工具用法卡片tool-usage cards使用独立的契约与必填tools字段不在本次范围内。审计只核查实现与引用的一致性不评估用户实际调用了哪些工作流——因为本次未检查用量遥测数据。可执行 Schema 是 catalog/schema.py维护中的作者指南与起始卡片分别是 skills/AGENTS.md 与 skills/_template/SKILL_TEMPLATE.md。三者构成「运行时校验 → 写作规范 → 新卡起点」的完整链条。二、主工作流卡片字段契约2.1 保留字段与用途审计确认以下字段继续保留语义与用途如下表字段决策与用途name保留。必填、全局唯一的小写 kebab-case 标识供发现discovery、加载loading与定时任务引用。description保留。必填的发现文本说明行为与激活条件。getting_started保留。可选的菜单标签必须与demo_order成对声明。demo_order保留。正整数决定生成菜单中的排序标签与序号均须唯一。pre_execute保留。至多一个ask_user_choice入口调用通过批量questions载荷可一次询问多个问题。它不能执行任意工具。includes由 frontmatter 中的references重命名而来。本地 Markdown 指令自动追加缺失文件、位于技能树之外、以及另一个SKILL.md都会被拒绝。recurring保留为布尔值默认false。标记是否可被循环技能运行器接管cron 与时区属于定时任务本身。metadata.owner保留必填。原始作者强调自然人归属。metadata.last_changed_by保留必填。最近一次编辑的负责人。metadata.last_changed_at保留必填。不带引号的 ISO 日期不得晚于当天。metadata.version保留必填字符串。编辑版本号调度器修订固定revision pin仍使用加载正文的哈希。metadata.usecases保留必填。非空字符串列表命名目标用户与具体场景。metadata.requires保留必填。非空字符串列表命名工具、凭证、访问权限与执行前提缺失、为空或格式错误会导致 CI 失败。六个 metadata 字段保留了项目希望在 NVIDIA 风格卡片中呈现的归属、用例与前提内容。需要强调这套 YAML Schema 是 OpenSRE 自身的表达方式并不意味着 NVIDIA 官方规定了这些键名NVIDIA 技能卡片与发布清单仅作为设计参考。2.2 移除的字段与机制metadata.type、metadata.dependencies、metadata.prerequisite_for全部移除。主工作流tools字段及其对后续菜单答案的局部工具过滤被移除。必要能力继续放在metadata.requires工具用法卡片保留各自必填的tools字段。after_tool、options_from、options_extra以及它们未使用的钩子状态与仓库选择器机制全部移除。手写主菜单选项与交接映射被移除。现在两者都由子技能 metadata 派生之后追加 Skip 选项生成出的菜单同样要经过校验。可选的references/slug.md文件仍通过skill_view按需加载Markdown 引用仍是 Markdown 链接二者都不是自动的includes条目——内容模块 与 AGENTS.md 中「includes 与 references 是两套机制」的表述完全一致。三、主工作流清单九个保留、一个移除技能结论onboarding-github-ci保留已实现工作流的入口菜单。analyzing-github-ci-performance保留历史 CI 指标分析。其调度交接文案存在陈旧描述见下文发现 2。scheduling-github-ci-fixes保留循环修复搭建与私有演示。当前 v5 指令存在下文描述的 checkout 不一致。connecting-slack保留Slack 接入与交接说明现为第三个演示项。fixing-github-ci保留一次性修复。工具调用细节与其工具用法卡片重叠下次编辑该工作流时应合并这些细节。fixing-github-security-alerts保留受支持的 GitHub 安全告警修复。类似的工具指引重叠不足以让该工作流过时。investigating-incidents-with-runbooks保留受支持的 runbook 调查。其格式与缺失默认计划需与作者指南对齐。reporting-github-ci-failures保留现行失败报告与调度发现。部分无人值守执行文案冗余。delivering-morning-briefings保留用例在依赖每种已配置的 Slack 模式之前需更新投递假设。delegating-github-ci-fixes移除明确的未实现托管服务占位符。三个已实现的 onboarding 子技能现在使用可复用的规范名称不带onboarding-前缀查询别名lookup aliases仍保留旧名。贡献者的AGENTS.md不参与技能发现。从 目录清单 可以看到a-analyzing-github-ci-performance/、b-scheduling-github-ci-fixes/、c-connecting-slack/三个子目录即对应演示 A/B/C。四、metadata 清理之外的四处工作流发现审计在元数据清理之外还确认了四处需要定向维护的运行时陈述问题定时修复的工作区workspace不一致并发修订的 v5 卡片声称修复器会克隆仓库、且在保存的工具调用中省略workspace但修复器实际要求一个 origin 匹配的既有 checkout。演示中的临时克隆必须带入保存的调用或宿主必须已默认使用该 checkout。证据b-scheduling-github-ci-fixes/SKILL.md 第 51 行与 ci_fix/runner.py 第 59 行的工作区校验ensure_push_ready及后续对 checkout/工作树的校验链。分析交接handoff卡片称调度工作流有一个「复用今日报告」的分析步骤但当前调度工作流实际是修复 PR。其交接应携带已选仓库并遵循已加载的修复计划。证据a-analyzing-github-ci-performance/SKILL.md 第 144 行。早间投递卡片指示在无用户请求时向 Slack 发帖假设每个 Slack 连接都有绑定 webhook 的目标并指向一个不存在的 fallback 小节。Slack bot-token 路径需要 channel。需澄清授权的投递方式、已配置目标以及无投递工具可用时的响应。证据delivering-morning-briefings/SKILL.md 第 102 行与 slack_send_message_tool/tool.py 第 108 行。从卡片正文可见第 4 步确实默认强制 Slack 投递webhook 绑定单一预配置 channel故不问用户选哪个频道而第 5 步才通过propose_scheduled_delivery提供循环化选项。循环 CI 报告文案其定时运行器直接产出报告因此指示无人值守 Agent 重新生成报告的指令是冗余的。应保留卡片的发现与调度角色。证据scheduled_skill_runner.py 第 61 行。审计结论明确这些发现指向定向工作流维护不构成删除九个保留用例的理由对调度工作流与 GitHub 修复实现的并发变更均被保留。五、执行与验证双层校验机制5.1 运行时坏卡可被排除但不阻断启动运行时发现会记录并排除无效卡片带诊断日志继续加载有效卡片。对应实现位于 registry.pyread_skill_catalog()第 59 行起遍历每个发现的卡片文件validate_skill_file()解析 frontmatter、构造SkillCard模型、加载script_tools并解析includes任何SkillCardError/ValidationError都会进入 diagnostics 而非中断遍历list_action_skills()第 92 行以lru_cache缓存结果对每条诊断打Skipping invalid skill警告后返回有效卡片集实现「排除坏卡、继续启动」。5.2 CI原始卡片全量校验坏卡无法藏进发布CI 在过滤之前校验原始卡片通过read_skill_catalog()读取全部原始卡片并让任何诊断失败。这样一来即使某张卡在运行时被排除也无法悄悄进入发布版本。作者侧对应make lint、make format-check、make typecheck以及面向技能加载、提示词、会话状态、动作轮次、交互菜单、定时技能与同址工作流测试的聚焦测试集。5.3 测试覆盖范围测试覆盖缺失前提、不支持的字段、非法 YAML/日期/编码、重复名称与重复键、非法 includes、无法渲染或含义模糊的菜单、真实入口行为、以及生成的交接handoffs。例如 test_skill_metadata.py 专门让last_changed_at缺失、非日期或未来日期的卡片失败。审计本身未执行任何线上 GitHub 演示、推送、部署或外部消息。六、从 Schema 到卡片字段级实现佐证对照 schema.py 可以逐字段印证上文契约严格模式所有模型继承_StrictModelextraforbid, strictTrue未知字段直接报错——这正是「不支持的字段」能被拒绝的机制_UniqueKeyLoader在 YAML 解析层就拒绝重复映射键防止字段被静默覆盖。name约束Field(patternr^[a-z0-9](?:-[a-z0-9])*$)强制小写 kebab-caseSkillCard之外registry.py用Counter对name、getting_started标签、demo_order序号做全局唯一性检查。pre_execute类型为list[SkillEntryCall]且max_length1tool被Literal[ask_user_choice]锁定args必须通过_EntryArguments校验含questions数量 2–6、选项 2–8 且去重、标题在空白折叠后仍唯一等规则validate_demo模型校验器还规定 onboarding 主卡必须恰好有一个单选的pre_execute菜单且不得自带options——选项由子技能 demo metadata 生成。metadata六字段SkillMetadata强制usecases/requires为非空列表owner/last_changed_by通过person_name校验器拒绝团队标签last_changed_at通过change_date拒绝未来日期。includesvalidate_skill_file中逐个调用files.resolve_skill_include(skill_path, ref)解析失败即抛错落实「仅限技能树内本地 Markdown、且非另一个 SKILL.md」的约束。七、写作该契约的新卡模板与版本纪律新主工作流卡片从 _template/SKILL_TEMPLATE.md 复制frontmatter 提供verb-ing-object的name占位、六字段 metadata、可选的recurring/getting_started/demo_order/includes注释示例正文固定为「目的 →## Plan检查清单 →## Workflow编号步骤」每个步骤须写明Complete when …的可观察完成条件。版本纪律AGENTS.md要点version写作带引号的MAJOR.MINOR字符串每次编辑让点号后的数字 12.1 → 2.2 → … → 2.9 → 2.10小数部分只是计数器而非十进制常规编辑措辞、步骤重排、新检查、更大的报告不动主版本号只有破坏卡片外部依赖时重命名、增删pre_execute问题、删除被持久化调度或同址测试依赖的步骤才升主版本并将次版本归零last_changed_by、last_changed_at、version三者必须同一次改动一起更新日期取自git log -1 --format%ad --dateshort -- SKILL.md。命名上技能名遵循verb-ing-object形态、厂商名作宾语形容词fixing-github-ci而非github-ci-fix、不加-demo/-agent/-tool后缀、仅已实现工作流可被发现重命名需把旧 slug 加入 catalog/naming.py 的LEGACY_SKILL_NAMES让持久化调度任务在下次 tick 自动重新固定到新名称。八、结语契约即审计的边界这次审计的价值在于划清了「什么是契约、什么需要维护、如何被强制」三条边界字段契约由 schema 在运行时与 CI 双层强制执行九条工作流通过定向维护保持正确而验证闭环由make lint、make format-check、make typecheck与聚焦测试共同兜底。对于想要为 OpenSRE 贡献新技能或排查既有技能加载问题的读者本文给出的字段表、schema 路径与校验链路即是完整的起点。【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/15 16:55:21 · 阅读 1.2k OpenSRE 技能卡片契约：主工作流 SKILL.md 的元数据 Schema、审计结论与发布校验
OpenSRE 技能卡片契约主工作流 SKILL.md 的元数据 Schema、审计结论与发布校验【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensreOpenSRE 将「AI SRE Agent」的多步工作流沉淀为带 YAML frontmatter 的SKILL.md技能卡片本文以仓库根目录下的 SKILL_CONTRACT_REVIEW.md 为骨架完整还原这份主工作流契约的审计结论——包括九个保留技能与一个移除技能、四项运行时陈述修正、以及从 schema 到 CI 的双层校验机制并结合 schema.py、AGENTS.md、registry.py 等源码给出实现级佐证。读完本文你将掌握主工作流卡片允许的完整字段集与六元 metadata 的写法、菜单/包含/脚本工具等机制如何被严格校验、以及一次契约审计应当如何形成「可复现的核查结论」。一、审计背景与契约定义审计执行于 2026-09-12对象是core/agent_harness/prompts/skills/目录下全部主工作流main workflow卡片。工具用法卡片tool-usage cards使用独立的契约与必填tools字段不在本次范围内。审计只核查实现与引用的一致性不评估用户实际调用了哪些工作流——因为本次未检查用量遥测数据。可执行 Schema 是 catalog/schema.py维护中的作者指南与起始卡片分别是 skills/AGENTS.md 与 skills/_template/SKILL_TEMPLATE.md。三者构成「运行时校验 → 写作规范 → 新卡起点」的完整链条。二、主工作流卡片字段契约2.1 保留字段与用途审计确认以下字段继续保留语义与用途如下表字段决策与用途name保留。必填、全局唯一的小写 kebab-case 标识供发现discovery、加载loading与定时任务引用。description保留。必填的发现文本说明行为与激活条件。getting_started保留。可选的菜单标签必须与demo_order成对声明。demo_order保留。正整数决定生成菜单中的排序标签与序号均须唯一。pre_execute保留。至多一个ask_user_choice入口调用通过批量questions载荷可一次询问多个问题。它不能执行任意工具。includes由 frontmatter 中的references重命名而来。本地 Markdown 指令自动追加缺失文件、位于技能树之外、以及另一个SKILL.md都会被拒绝。recurring保留为布尔值默认false。标记是否可被循环技能运行器接管cron 与时区属于定时任务本身。metadata.owner保留必填。原始作者强调自然人归属。metadata.last_changed_by保留必填。最近一次编辑的负责人。metadata.last_changed_at保留必填。不带引号的 ISO 日期不得晚于当天。metadata.version保留必填字符串。编辑版本号调度器修订固定revision pin仍使用加载正文的哈希。metadata.usecases保留必填。非空字符串列表命名目标用户与具体场景。metadata.requires保留必填。非空字符串列表命名工具、凭证、访问权限与执行前提缺失、为空或格式错误会导致 CI 失败。六个 metadata 字段保留了项目希望在 NVIDIA 风格卡片中呈现的归属、用例与前提内容。需要强调这套 YAML Schema 是 OpenSRE 自身的表达方式并不意味着 NVIDIA 官方规定了这些键名NVIDIA 技能卡片与发布清单仅作为设计参考。2.2 移除的字段与机制metadata.type、metadata.dependencies、metadata.prerequisite_for全部移除。主工作流tools字段及其对后续菜单答案的局部工具过滤被移除。必要能力继续放在metadata.requires工具用法卡片保留各自必填的tools字段。after_tool、options_from、options_extra以及它们未使用的钩子状态与仓库选择器机制全部移除。手写主菜单选项与交接映射被移除。现在两者都由子技能 metadata 派生之后追加 Skip 选项生成出的菜单同样要经过校验。可选的references/slug.md文件仍通过skill_view按需加载Markdown 引用仍是 Markdown 链接二者都不是自动的includes条目——内容模块 与 AGENTS.md 中「includes 与 references 是两套机制」的表述完全一致。三、主工作流清单九个保留、一个移除技能结论onboarding-github-ci保留已实现工作流的入口菜单。analyzing-github-ci-performance保留历史 CI 指标分析。其调度交接文案存在陈旧描述见下文发现 2。scheduling-github-ci-fixes保留循环修复搭建与私有演示。当前 v5 指令存在下文描述的 checkout 不一致。connecting-slack保留Slack 接入与交接说明现为第三个演示项。fixing-github-ci保留一次性修复。工具调用细节与其工具用法卡片重叠下次编辑该工作流时应合并这些细节。fixing-github-security-alerts保留受支持的 GitHub 安全告警修复。类似的工具指引重叠不足以让该工作流过时。investigating-incidents-with-runbooks保留受支持的 runbook 调查。其格式与缺失默认计划需与作者指南对齐。reporting-github-ci-failures保留现行失败报告与调度发现。部分无人值守执行文案冗余。delivering-morning-briefings保留用例在依赖每种已配置的 Slack 模式之前需更新投递假设。delegating-github-ci-fixes移除明确的未实现托管服务占位符。三个已实现的 onboarding 子技能现在使用可复用的规范名称不带onboarding-前缀查询别名lookup aliases仍保留旧名。贡献者的AGENTS.md不参与技能发现。从 目录清单 可以看到a-analyzing-github-ci-performance/、b-scheduling-github-ci-fixes/、c-connecting-slack/三个子目录即对应演示 A/B/C。四、metadata 清理之外的四处工作流发现审计在元数据清理之外还确认了四处需要定向维护的运行时陈述问题定时修复的工作区workspace不一致并发修订的 v5 卡片声称修复器会克隆仓库、且在保存的工具调用中省略workspace但修复器实际要求一个 origin 匹配的既有 checkout。演示中的临时克隆必须带入保存的调用或宿主必须已默认使用该 checkout。证据b-scheduling-github-ci-fixes/SKILL.md 第 51 行与 ci_fix/runner.py 第 59 行的工作区校验ensure_push_ready及后续对 checkout/工作树的校验链。分析交接handoff卡片称调度工作流有一个「复用今日报告」的分析步骤但当前调度工作流实际是修复 PR。其交接应携带已选仓库并遵循已加载的修复计划。证据a-analyzing-github-ci-performance/SKILL.md 第 144 行。早间投递卡片指示在无用户请求时向 Slack 发帖假设每个 Slack 连接都有绑定 webhook 的目标并指向一个不存在的 fallback 小节。Slack bot-token 路径需要 channel。需澄清授权的投递方式、已配置目标以及无投递工具可用时的响应。证据delivering-morning-briefings/SKILL.md 第 102 行与 slack_send_message_tool/tool.py 第 108 行。从卡片正文可见第 4 步确实默认强制 Slack 投递webhook 绑定单一预配置 channel故不问用户选哪个频道而第 5 步才通过propose_scheduled_delivery提供循环化选项。循环 CI 报告文案其定时运行器直接产出报告因此指示无人值守 Agent 重新生成报告的指令是冗余的。应保留卡片的发现与调度角色。证据scheduled_skill_runner.py 第 61 行。审计结论明确这些发现指向定向工作流维护不构成删除九个保留用例的理由对调度工作流与 GitHub 修复实现的并发变更均被保留。五、执行与验证双层校验机制5.1 运行时坏卡可被排除但不阻断启动运行时发现会记录并排除无效卡片带诊断日志继续加载有效卡片。对应实现位于 registry.pyread_skill_catalog()第 59 行起遍历每个发现的卡片文件validate_skill_file()解析 frontmatter、构造SkillCard模型、加载script_tools并解析includes任何SkillCardError/ValidationError都会进入 diagnostics 而非中断遍历list_action_skills()第 92 行以lru_cache缓存结果对每条诊断打Skipping invalid skill警告后返回有效卡片集实现「排除坏卡、继续启动」。5.2 CI原始卡片全量校验坏卡无法藏进发布CI 在过滤之前校验原始卡片通过read_skill_catalog()读取全部原始卡片并让任何诊断失败。这样一来即使某张卡在运行时被排除也无法悄悄进入发布版本。作者侧对应make lint、make format-check、make typecheck以及面向技能加载、提示词、会话状态、动作轮次、交互菜单、定时技能与同址工作流测试的聚焦测试集。5.3 测试覆盖范围测试覆盖缺失前提、不支持的字段、非法 YAML/日期/编码、重复名称与重复键、非法 includes、无法渲染或含义模糊的菜单、真实入口行为、以及生成的交接handoffs。例如 test_skill_metadata.py 专门让last_changed_at缺失、非日期或未来日期的卡片失败。审计本身未执行任何线上 GitHub 演示、推送、部署或外部消息。六、从 Schema 到卡片字段级实现佐证对照 schema.py 可以逐字段印证上文契约严格模式所有模型继承_StrictModelextraforbid, strictTrue未知字段直接报错——这正是「不支持的字段」能被拒绝的机制_UniqueKeyLoader在 YAML 解析层就拒绝重复映射键防止字段被静默覆盖。name约束Field(patternr^[a-z0-9](?:-[a-z0-9])*$)强制小写 kebab-caseSkillCard之外registry.py用Counter对name、getting_started标签、demo_order序号做全局唯一性检查。pre_execute类型为list[SkillEntryCall]且max_length1tool被Literal[ask_user_choice]锁定args必须通过_EntryArguments校验含questions数量 2–6、选项 2–8 且去重、标题在空白折叠后仍唯一等规则validate_demo模型校验器还规定 onboarding 主卡必须恰好有一个单选的pre_execute菜单且不得自带options——选项由子技能 demo metadata 生成。metadata六字段SkillMetadata强制usecases/requires为非空列表owner/last_changed_by通过person_name校验器拒绝团队标签last_changed_at通过change_date拒绝未来日期。includesvalidate_skill_file中逐个调用files.resolve_skill_include(skill_path, ref)解析失败即抛错落实「仅限技能树内本地 Markdown、且非另一个 SKILL.md」的约束。七、写作该契约的新卡模板与版本纪律新主工作流卡片从 _template/SKILL_TEMPLATE.md 复制frontmatter 提供verb-ing-object的name占位、六字段 metadata、可选的recurring/getting_started/demo_order/includes注释示例正文固定为「目的 →## Plan检查清单 →## Workflow编号步骤」每个步骤须写明Complete when …的可观察完成条件。版本纪律AGENTS.md要点version写作带引号的MAJOR.MINOR字符串每次编辑让点号后的数字 12.1 → 2.2 → … → 2.9 → 2.10小数部分只是计数器而非十进制常规编辑措辞、步骤重排、新检查、更大的报告不动主版本号只有破坏卡片外部依赖时重命名、增删pre_execute问题、删除被持久化调度或同址测试依赖的步骤才升主版本并将次版本归零last_changed_by、last_changed_at、version三者必须同一次改动一起更新日期取自git log -1 --format%ad --dateshort -- SKILL.md。命名上技能名遵循verb-ing-object形态、厂商名作宾语形容词fixing-github-ci而非github-ci-fix、不加-demo/-agent/-tool后缀、仅已实现工作流可被发现重命名需把旧 slug 加入 catalog/naming.py 的LEGACY_SKILL_NAMES让持久化调度任务在下次 tick 自动重新固定到新名称。八、结语契约即审计的边界这次审计的价值在于划清了「什么是契约、什么需要维护、如何被强制」三条边界字段契约由 schema 在运行时与 CI 双层强制执行九条工作流通过定向维护保持正确而验证闭环由make lint、make format-check、make typecheck与聚焦测试共同兜底。对于想要为 OpenSRE 贡献新技能或排查既有技能加载问题的读者本文给出的字段表、schema 路径与校验链路即是完整的起点。【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考