publish-and-sync-skills

发布并同步技能

执行一次发布流程：

仓库源代码 → 验证 → 合并到 GitHub → 全局安装 → 留存证据。

将 JoelFrancisco/skills 视为唯一可信来源。将全局 Agent 目录视为生成的安装目录。

选择发布路径

选择一个入口：

• 添加或导入： 执行所有步骤。
• 更新： 从准备仓库开始，编辑现有技能，然后执行从注册到验证的步骤。
• 仅同步： 确认请求的技能已合并到 main，然后从全局安装开始。

完整的发布并同步请求包含合并授权。仅请求 PR 时，完成草稿的发布后即停止。

1. 准备仓库

找到一个 origin 指向 JoelFrancisco/skills 的检出目录。在更改结构或发布行为之前，阅读仓库说明、docs/creating-skills.md 和已接受的 ADR。

将干净的 main 与 origin/main 同步，然后创建 agent/<skill-name>。通过隔离或在暂存之前询问范围，保留无关工作。

当检出目录位于一个基于最新 origin/main 的专用分支上，且每项现有更改都有明确负责人时，即可完成此步骤。

2. 添加或更新技能

按照仓库约定选择当前类别。保持文件夹名称、frontmatter 中的 name 和 kebab-case 技能名称一致。

对于新技能，使用当前 harness 的技能编写脚手架。如果 harness 仅提供手动编写方式，则创建：

skills/<category>/<skill-name>/
├── SKILL.md
└── agents/openai.yaml

对于导入的公开技能，在改编之前检查其许可证、来源、脚本、网络行为、凭据使用情况和破坏性操作。保留导入材料所需的署名信息。

编写面向模型的描述，说明技能的功能，并为每个实际分支提供一个触发条件。正文应使用祈使语气、内容自包含且不含占位符。将详细或有条件的内容放入同级文件，并提供明确的上下文指引。

当技能只有一个明确用途、所有占位符都已解决、UI 元数据有效，且每个操作步骤都有可检查的完成标准时，即可完成此步骤。

3. 注册并为发布版本编号

重新生成精选清单：

node scripts/sync-skills.mjs

同时提升 .claude-plugin/plugin.json 和 .claude-plugin/marketplace.json 中的发布版本号。两处值必须相同。新增公开技能通常应提升次版本号；兼容性修正通常应提升修订版本号。

当新技能路径在 plugin.json 中恰好出现一次、清单仅包含当前类别的技能，且两个清单均包含相同的预期版本号时，即可完成此步骤。

4. 发布前验证

运行所有适用的检查：

node scripts/sync-skills.mjs --check
jq empty .claude-plugin/plugin.json .claude-plugin/marketplace.json
git diff --check
npx --yes skills@latest add . --list --full-depth

如果当前 harness 提供技能验证器，则运行该验证器。使用有代表性的输入执行每个打包脚本。对于复杂技能，使用只接收该技能和真实任务的新 Agent 进行前向测试。

当清单发现功能列出该技能、结构检查通过、可执行资源通过，且前向测试中的失败已修正或明确报告时，即可完成此步骤。

5. 发布并合并

检查完整差异，只暂存发布文件。在专用分支上创建简短的提交说明，推送并设置跟踪，然后开启草稿 PR，在正文中说明更改内容、原因、影响和验证情况。

如果请求包含完整发布：

1. 确认 PR 的目标分支、预期 head SHA、可合并状态、评审和检查结果。
2. 将 PR 标记为准备就绪，并使用仓库认可的方式合并。
3. 将本地检出切换到 main，并使用 --ff-only 拉取。

优先使用可用的 GitHub 集成；对于不支持的修改操作，使用已认证的 gh CLI 作为后备方案。

对于仅创建 PR 的发布，当草稿 PR 包含预期差异和验证证据时，即可完成此步骤。对于完整发布，当 GitHub 显示 PR 已合并、本地 main 包含该合并，且工作树干净时，即可完成此步骤。

6. 全局安装合并后的技能

通过运行 npx --yes skills@latest --help 确认当前 Vercel Skills CLI 语法。定义此 shell 辅助函数，然后使用准确的合并后技能名称调用 sync_public_skill：

sync_public_skill() {
  local released_skill="$1"
  npx --yes skills@latest add JoelFrancisco/skills \
    --global \
    --agent codex claude-code hermes-agent opencode pi \
    --skill "$released_skill" \
    --yes \
    --full-depth
}

该命令使用 CLI 的默认符号链接安装模式。规范的运行环境标识符为 codex、claude-code、hermes-agent、opencode 和 pi。

当 CLI 报告已为全部五种运行环境安装所请求的技能时，即完成此步骤。

7. 验证本地同步

以 JSON 格式列出全局安装，并选择已发布的技能：

npx --yes skills@latest list --global --json

请验证：

• 作用域为全局；
• 来源为 JoelFrancisco/skills；
• Codex、Claude Code、Hermes Agent、OpenCode 和 Pi 均已列出；
• 在 CLI 使用符号链接的情况下，特定 Agent 的链接均指向规范安装位置；
• 已安装的 SKILL.md 内容与合并后的仓库版本一致。

当 GitHub 合并、本地 main、清单版本、全局来源、五种运行环境和已安装内容全部一致时，即完成发布流程。

报告发布情况

先说明结果。包括技能名称和路径、发布版本、提交、PR 和合并情况、验证结果、安装来源、运行环境覆盖范围，以及任何仍未验证的事项。

报告需完整自洽，并明确区分已通过、失败和未验证的证据。