skill-publisher

技能发布器

从技能管理器仓库准备、打包并发布技能到其配置的 GitHub 仓库。支持以下布局：

• 独立技能： skills/<skill-id>/ → <github.owner>/<skill-id>。
• 系列技能： skills/<series>/<skill-id>/ → 该系列配置的仓库和目标路径。

此技能仅发布用户拥有或获授权维护的技能。不会搜索、安装或重新发布无关的第三方技能。

操作模式

根据用户的请求推断所需模式，并简要说明：

• 审计 / 检查： 检查元数据和完整性；不要更改文件或远程状态。
• 准备 / 打包： 验证并构建本地制品；不要修改远程仓库。
• 发布 / 上线： 准备制品，提供明确的发布计划，在进行远程修改前取得明确确认，然后发布并验证结果。

不要将检查或打包请求转变为发布请求。

不可妥协的安全规则

1. 未经确认，不得修改远程状态。 在创建仓库、推送提交、更改可见性、打开或合并 PR、创建标签 / 发布版本或修改发布元数据之前，说明确切的目标、可见性、分支、版本、文件和操作。取得明确确认。每项实质上不同的操作都需要重新确认。
2. 不得使用破坏性 Git 快捷操作。 绝不强制推送、强制更新标签、删除 / 重建发布版本、运行 git reset --hard，或使用 git clean -fdx 来简化发布。不得覆盖目标仓库中无关的文件。
3. 保护本地工作。 编辑或提交前检查 git status。保留用户的更改。不得将无关的已暂存或未跟踪文件纳入发布提交。如果工作区状态导致无法明确安全隔离，则停止并说明阻碍。
4. 不得猜测配置。 阅读 series.json 和目标技能的 SKILL.md；根据实际配置确定目标。如果缺少系列目标，或技能引用存在歧义，应报告已准备就绪的内容和缺少的配置，而不是自行编造仓库。
5. 绝不泄露凭据。 使用 gh auth status 检查身份验证状态。不要打印令牌、复制凭据文件、在 URL 中嵌入机密，或要求用户在聊天中粘贴凭据。
6. 版本不可变。 绝不静默覆盖现有版本标签或 GitHub Release。如果版本已存在，应比较已发布状态；只有在能够确认等效时才报告“已发布”。否则停止并建议使用新版本。
7. 将发布前检查与发布后检查分开。 对于首次发布，不能将匹配的 GitHub Release 作为创建该版本发布的前提。发布前检查冲突；仅在发布后验证发布版本是否存在。
8. 如实说明验证情况。 区分实际运行的检查与仅建议运行的检查。未检查命令结果并验证远程状态前，绝不能声称打包、推送或发布已成功。

工作流

1. 确定技能和目标

1. 找到技能管理器仓库根目录和用户请求的技能文件夹。
2. 规范化技能引用。独立技能使用 <skill-id>，系列技能使用 <series>/<skill-id>。如果多个系列中存在相同 ID，则要求用户提供明确的系列限定引用。
3. 阅读相关技能的 SKILL.md、README.md、LICENSE、任何 agents/ 元数据，以及相关的 series.json。
4. 根据配置确定目标仓库和仓库内路径。仅当明确配置了 github.owner 时，才可根据该所有者和技能 ID 推导独立技能的目标。不要假设目标仓库的默认分支名为 main。

2. 明确意图和发布版本

1. 确定用户要求的是审计、打包还是发布。仅凭检查或准备请求，不要推断用户授权进行远程变更。
2. 从技能 front matter 中读取 metadata.version，并在可访问时检查相关 Git 标签 / GitHub Releases。
3. 使用语义化版本控制：
   • PATCH： 向后兼容的修复、措辞更正和内部说明，不增加实质性能力。
   • MINOR： 增加工作流、能力或指导，同时与现有用途和接口兼容。
   • MAJOR： 对技能预期工作流、接口、元数据契约或支持的布局进行不兼容变更。
4. 不要仅因重新构建软件包就升级版本。如果必须升级版本，但预期发布范围不明确，应建议一个版本，并在更改前征求确认。切勿根据无法访问的标签臆造版本。
5. 将 SKILL.md 中的版本作为唯一可信的源版本。确保软件包清单、目标仓库内容、Git 标签和 Release 名称都与其一致。

3. 验证技能

运行仓库实际使用的验证命令，并将所有报告的错误视为阻断项：

skillctl check --skill <skill-ref>

如果入口点不可用，且管理仓库支持文档中所述的备用方案，请使用：

PYTHONPATH=src python -m skill_manager check --skill <skill-ref>

如果这两种命令都不可用，不要臆造替代命令。报告阻断项，并仅继续进行不依赖缺失验证器的非破坏性审查。

至少确认以下内容：

• front matter 是可解析的 YAML，并包含有效的技能 name、有用的 description、符合语义化版本规范的 metadata.version、metadata.license 和非空的 metadata.topics；
• 在管理器要求的情况下，技能目录名与 front matter 中的名称一致；
• README.md 说明了用途、要求、用法、限制和发布流程；
• 许可证文件存在，且符合预期的复用条款；
• 技能引用的文件和路径均存在；
• 示例和命令与实际管理器及仓库布局一致。

不要通过弱化或删除完整性门槛来“修复”验证失败。

4. 打包并检查产物

仅在验证通过后运行打包命令：

skillctl package --skill <skill-ref>

打包过程必须再次运行验证门槛。不要只相信退出码，还要检查生成的归档：

• 确认产物存在、可打开，且包含预期的技能文件；
• 检查 MANIFEST.json，确认技能 ID、版本、许可证、主题和入口点正确；
• 检查是否包含无关项目文件、.git/、虚拟环境、缓存、凭据、.env 文件、私钥或意外的本地产物；
• 确认引用的支持文件已包含在内，且路径可移植；
• 保持打包结果可重复；验证后不要修改归档内容，如有修改，应重新打包并再次检查。

如果命令未清楚显示输出路径，请检查其帮助信息或输出内容。不要猜测产物文件名。

5. 预检 GitHub 目标

对于发布请求：

1. 使用 gh auth status 检查身份验证；不要泄露身份验证详情。
2. 如果目标仓库存在，使用 GitHub CLI 或其他可用的只读方式检查。记录其规范所有者/名称、可见性、URL、默认分支、描述、主题、README、许可证，以及可获取的分支保护限制。
3. 查询实际的默认分支；切勿将 main 写死。
4. 检查 v<version>（或仓库文档规定的标签约定）是否已作为 Git 标签或 Release 存在。准备推送前解决冲突。
5. 区分必须在发布前存在的元数据（仓库描述、主题、README、许可证、正确的技能文件）与发布后核验的元数据（标签、Release 页面、说明和附加的软件包资源）。
6. 如果目标仓库不存在，提出仓库名称、描述、主题、目标路径和可见性。默认使用私有可见性，除非用户明确要求公开；创建前须获得明确确认。
7. 如果尚未配置系列目标，请停止远程发布。仍可报告软件包已准备就绪。

6. 提交发布计划并取得确认

首次进行任何远程更改前，概述：

• 源技能以及当前/拟定版本；
• 验证和软件包结果；
• 确切的目标仓库 URL 和可见性；
• 目标路径和实际默认分支；
• 将添加、更新或移除的文件（通常不移除任何文件，除非明确列出）；
• 计划采用的提交/分支/PR 策略；
• 标签和 Release 名称、说明来源，以及要附加的软件包资源；
• 任何仓库元数据更改。

请用户确认此具体计划。如果目标位置、可见性、版本或受影响的文件此后发生变化，不要依赖先前含糊的指示。

7. 安全暂存更改

1. 确认后、写入前，重新检查目标的最新远程状态。
2. 优先使用独立克隆、工作树或专用发布检出目录。使用前确认其远程源和当前分支。
3. 获取目标实际的默认分支。保留现有文件和仓库专属工作流。仅将经过验证的技能文件复制到配置的目标路径；切勿整体复制管理器仓库。
4. 检查差异和状态。确认拟提交内容中没有无关更改。不要仅因为某些仓库文件未出现在源技能文件夹中，就删除这些文件。
5. 仅提交确切的预期技能文件。如果仓库要求使用分支或拉取请求，请遵循该策略，不要绕过保护。仅当用户明确批准该方式且仓库策略允许时，才可直接推送到默认分支。
6. 切勿强制推送或丢弃目标仓库中的并发更改。如果远程已有新进展，请获取并安全协调；如果无法在不猜测的情况下解决冲突，请停止操作。

8. 创建 GitHub Release

仅在目标内容已推送或所需 PR 已合并后：

1. 确认预期的目标提交包含经过验证的技能文件。
2. 确保目标版本标签和 Release 未指向不同内容。
3. 根据实际差异或提供的变更日志生成简洁、准确的发布说明。不要声称未经验证的测试结果或功能。
4. 除非目标仓库文档规定了其他约定，否则使用 v<version> 创建 Release。
5. 如果已生成相应软件包，且发布计划包含该软件包，则附加软件包步骤生成的、经过验证且确定性的 ZIP。不要将无关文件改名后当作软件包。
6. 不要覆盖现有 Release 或标签。如果预检与创建之间出现冲突，请停止并报告。

9. 验证并报告

发布后，在工具允许的情况下，独立验证远程结果：

• 目标仓库和已发布路径正确；
• 预期提交已存在于预期分支；
• 标签和 Release 名称与技能版本一致；
• Release URL 和发行说明可用；
• 如计划附加预期的软件包资源，该资源已附加且可下载；
• 仓库描述、主题、README 和许可证准确无误；
• 未发布无关文件或机密信息。

返回一份简洁报告，列出源技能、版本、目标 URL、提交/分支、Release URL、构件路径、已通过的检查、未运行的检查以及任何遗留问题。对于仅打包模式，提供本地构件路径，并明确说明未发布任何内容。

失败处理与恢复

• **验证失败：**停止打包和发布；列出失败的检查以及最小且安全的修复方案。
• **打包失败：**保留源文件，检查错误，并在修复原因后重新构建。
• **身份验证或权限失败：**停止操作；报告缺少的权限类别，不要泄露机密信息。
• **缺少系列目标位置：**报告本地验证/打包可能已完成，但因配置问题而无法发布。
• **工作树不干净或包含无关的暂存文件：**保留当前状态；在单独的工作树中隔离此版本发布，或请用户处理。
• **发布期间远程内容发生变化：**重新获取并检查差异，不要覆盖并发工作。
• **版本已发布：**比较标签、提交、源版本和资源。如果能确认完全等同，则报告已有版本；否则必须使用新版本，不能重写历史。
• **部分发布：**准确报告已成功的步骤。重新检查远程状态后，从第一个未完成的步骤继续；不要盲目重复创建仓库、推送、打标签或创建 Release。

最终限制

• 没有操作结果证据，以及（对于远程发布）回读检查，不得声称操作成功。
• 不得将推断出的建议当作事实。将无法进行的检查标注为 未验证。
• 面向用户的输出应聚焦于决策点、实际变更、验证情况和阻塞因素；不要输出凭据、大量命令日志或无关的仓库内容。