publish-skill

调用时机

• 用户说“发布 skill”“更新 skill”“推送 skill 变更”或“/publish-skill”
• 在 .agents/skills/ 中本地编辑 skill 后

步骤

1. 发布前检查

按以下顺序定位 ai-skills 路径：

1. $AI_SKILLS_REPO 环境变量
2. ~/projects/camacho/ai-skills
3. 询问用户

然后检查工作区是否干净：

git -C "$AI_SKILLS_PATH" status --porcelain

如果不为空：停止。告知用户先提交或暂存 ai-skills 的变更。

2. 检测新增和已修改的 skill

对于 .agents/skills/ 中的每个目录：

skill_name=$(basename "$dir")
local_hash=$(git hash-object ".agents/skills/$skill_name/SKILL.md" 2>/dev/null)
remote_hash=$(git hash-object "$AI_SKILLS_PATH/skills/$skill_name/SKILL.md" 2>/dev/null || echo "")

分类：

• remote_hash 为空 → 🆕 新增
• local_hash != remote_hash → ✏️ 已修改
• 相等 → 未变更，跳过

列出结果。继续之前先征求用户确认。记录每个 local_hash——第 7 步的安全检查需要用到。

3. 快照（回滚点）

对于每个已批准的 skill：

git add -f ".agents/skills/$skill_name/SKILL.md"
git commit -m "chore(skills): snapshot $skill_name before publish [publish-skill rollback point]"

如果发布在后续任一步骤失败，使用以下命令还原：

git checkout ".agents/skills/$skill_name/"

4. 代码审查

对 SKILL.md 差异（本地版本与 ai-skills 版本）运行 code-reviewer Agent。 审查重点：正确性、避免危险的 bash 命令、避免提示词注入向量。

发现 P0/P1 问题 → 停止。修复后再继续。 发现 P2 问题 → 记录，但不阻止流程。

5. 复制到 ai-skills 并推送

cp -r ".agents/skills/$skill_name" "$AI_SKILLS_PATH/skills/$skill_name"
git -C "$AI_SKILLS_PATH" add "skills/$skill_name"
git -C "$AI_SKILLS_PATH" commit -m "feat(skills): publish $skill_name"

提交所有 skill 后：

git -C "$AI_SKILLS_PATH" push

推送前先征求用户确认——这会影响使用这些 skill 的所有仓库。

6. 在本地安装

为每个 skill 检测作用范围——检查它应属于哪个锁文件：

REPO_ROOT="$(git rev-parse --show-toplevel)"
if jq -e --arg n "$skill_name" '.skills[$n]' "$REPO_ROOT/dotfiles/skills-lock.json" >/dev/null 2>&1; then
  SCOPE="user"
else
  SCOPE="project"
fi

npx skills add 使用 process.cwd() 作为安装目标。在链接工作树中，确保 CWD 是工作树根目录。

**源规范：**使用 github <owner>/<repo> 形式，而不是本地文件系统路径。本地路径会生成 sourceType: "local" 和特定于机器的 source 锁文件条目，这与其他仓库使用的 sourceType: "github" 条目冲突，并会导致合并失败。通过 ai-skills 远程仓库检测规范源，以确保在不同机器上都能正常工作：

AI_SKILLS_SPEC=$(git -C "$AI_SKILLS_PATH" remote get-url origin \
  | sed -E 's#(git@github\.com:|https://github\.com/|ssh://git@github\.com/|git://github\.com/)##; s#\.git$##; s#/$##')
# e.g. "camacho/ai-skills"

# Validate — bad spec must fail loudly, not silently re-introduce sourceType=local class of bug.
[[ "$AI_SKILLS_SPEC" =~ ^[^/]+/[^/]+$ ]] || { echo "bad spec: $AI_SKILLS_SPEC"; exit 1; }

cd "$REPO_ROOT"
if [ "$SCOPE" = "user" ]; then
  npx skills add "$AI_SKILLS_SPEC" --skill "$skill_name" -g -y
else
  npx skills add "$AI_SKILLS_SPEC" --skill "$skill_name" -y
fi

**不要使用 -a 标志。**默认安装会将规范副本写入 .agents/skills/<n>/，并创建 Claude Code 发现 skill 所需的 .claude/skills/<n> 符号链接。Codex 和 npx skills CLI 识别的其他“通用”Agent 会直接读取 .agents/skills/<n>/——无需按工具命名空间创建符号链接。传入 -a codex 不会创建符号链接；只将 -a claude-code 作为 Agent 目标传入，会强制将文件复制（而非创建符号链接）到 .claude/skills/<n>/，从而破坏规范源模型。只有默认安装（不使用 -a）才能生成正确的 .agents/ 规范副本 + .claude/ 符号链接布局。此结论已通过 npx skills add 标志矩阵实验进行实证验证（2026-05-14）。

github 规范源要求先推送源提交（第 5 步已完成推送），这样安装时拉取的就是刚刚发布的内容。

npx skills add 会自动更新相应的 skills-lock.json。

7. 安全哈希检查

对于每个已安装的 skill：

after_hash=$(git hash-object ".agents/skills/$skill_name/SKILL.md" 2>/dev/null)

将 after_hash 与第 2 步中发布前记录的 local_hash 进行比较。

如果不匹配：

• 还原：git checkout ".agents/skills/$skill_name/"
• 告知用户。停止。

8. 删除跟踪并提交锁文件

for skill_name in $approved_skills; do
  git rm --cached ".agents/skills/$skill_name/SKILL.md"
done
# Stage the lockfile that was updated (project or user)
git add skills-lock.json dotfiles/skills-lock.json 2>/dev/null || true
git commit -m "chore(skills): publish $approved_skills_csv — drop tracking, update lockfile"

LOCKFILE_SHA=$(git rev-parse HEAD)

9. 将锁文件提交 cherry-pick 到 TARGET

默认 TARGET=main。检查是否存在冲突：

git fetch origin "$TARGET"
git checkout "$TARGET"
git cherry-pick --no-commit "$LOCKFILE_SHA"
git status --porcelain

如果 skills-lock.json 存在冲突：停止。将冲突情况告知用户。 如果没有冲突：运行 git cherry-pick --continue（或者在使用 --no-commit 后运行 git commit），然后推送。

如果 CI 不可用：使用 BRANCH=current、TARGET=$TARGET 调用 /local-merge，而不是执行 cherry-pick + 推送。

集成

替代：/elevate-skill（仅处理本地 skill）。 配合使用：/build-skill（创建新 skill）和 /local-merge（第 9 步中 CI 不可用时的备用方案）。