RHDH Overlay 用于管理 rhdh-plugin-export-overlays 仓库和 Extensions Catalog，负责目录打包与 overlay 仓库操作。使用时应从一个远程指向 redhat-developer/rhdh-plugin-export-overlays 的检出开始，不依赖其他已安装技能的文件或 CLI。
用途与路由 该技能按目标结果路由到不同工作流：接入插件使用 workflows/onboard-plugin.md；更新源版本或提交使用 workflows/update-plugin.md；诊断导出或发布失败使用 workflows/fix-build.md；查询某分支或标签上的插件版本或安装产物则按元数据查找流程；检查工作区状态参考 references/overlay-repo.md，并检查工作区文件与最近的 gh 运行；分类开放 PR 积压使用 workflows/triage-prs.md，并用 scripts/triage-prs.py 做确定性分类；分析单个 overlay PR 使用 workflows/analyze-pr.md，并用 scripts/analyze-pr.py；草拟过期 PR 通知使用 workflows/draft-notification.md；触发发布则执行受保护的发布流程。遇到环境问题，遵循 workflows/doctor.md。
开始步骤 先阅读仓库说明并运行 gh auth status；用 git remote -v 确认检出与远程；在修改元数据前，检查目标工作区、一个相似工作区以及相关 PR 或 CI 日志。
元数据查找 对每次读取都使用请求的 overlay 分支或标签，默认 main。在该 ref 上读取 catalog-entities/extensions/plugins/<plugin-name>.yaml，解析 spec.packages，然后在同一 ref 的工作区 metadata/ 目录中定位每个 Package 实体。从这些实体报告 spec.packageName、spec.version 和 spec.dynamicArtifact。在 overlay 检出中使用 git show <ref>:<path>；如果 ref 或元数据缺失，应报告缺失，而不是回退到 main。实体字段可阅读 references/metadata-format.md。
不变量 每个导出都在 overlay 仓库中配置，由 CI 执行导出。source.json 的 repo-backstage-version 是上游源实际的 Backstage 版本；backstage.json 的 version 是 RHDH 兼容性覆盖值，两者不可互相替代。包和 ref 必须从上游与生成的元数据推导，绝不能凭空编造 OCI URL。当仓库约定与本技能示例不同时，复制一个当前相似工作区的结构。合并前，测试确切的 PR 产物；一个已加载插件的认证错误可能可以接受，但安装或启动错误不可接受。
受保护的发布 在发布 /publish 之前，确认 PR 处于打开状态、没有 do-not-merge 标签，且当前 head 没有成功的发布检查。发布评论属于外部写入：调用名为 mutation-gate 的技能并遵循其门控，而不是在此重述。需陈述一个操作，其目标是 redhat-developer/rhdh-plugin-export-overlays#<number>@<head-sha>，预览正文为 /publish，前置条件为上述三项检查，失败时若触发错误则报告该评论以供手动移除。只有在用户批准该陈述操作后，才运行：gh pr comment <number> --repo redhat-developer/rhdh-plugin-export-overlays --body "/publish"。报告评论与发布检查的 URL，或失败及其所需恢复。请求触发发布是读取 PR 的意图，不是对该写入的批准。
其他外部写入 同一门控覆盖工作流触及的每次推送、PR 创建、通知或其他外部写入。只有在目标和载荷确切时才陈述操作，不运行未在批准集合中的任何内容，并为每个操作报告结果，包括被跳过的操作。只读的分类与分析无需门控。
调用方提供与技能报告 调用方按名称调用此技能，并说明源仓库、源 ref（提交或标签）、包、上游 Backstage 版本和目标 RHDH 版本。技能报告工作区及其变更（源 ref、包、元数据文件）、CI 与本地验证证据（含跳过的检查及原因）、PR URL 或未打开 PR、发布状态（未请求、待处理、通过或失败）、每个已批准外部写入的结果，以及剩余的兼容性风险。
本地验证 进行本地验证时，按名称调用 /rhdh-local，并提供确切的产物引用、插件配置、命名环境变量和要运行的检查；不要加载本地技能的文件。
完成条件 当报告涵盖工作区与元数据变更、运行的命令与脚本、CI 与本地验证证据、每个已批准写入的结果、发布状态以及剩余兼容性风险时，任务完成。