用途
contribute-skill 用于把本地改修过的 skills/<skill-name>/ 目录,作为 PR 提交到 skills-lock.json 中记录的上游仓库(例如 Fandhe-AI/agent-cli-skills)。
它与 create-pr 的职责相互分离:
- create-pr:在当前仓库内,从当前分支向 base 创建 PR。
- contribute-skill:面向另一个仓库(upstream),执行 clone → 变更反映 → push → PR 创建。
由于外部仓库贡献涉及 clone、路径转换以及不同的认证边界,因此被拆分为独立技能。
前提条件
- 已安装并认证 gh CLI(需要对目标 org 具有 push / PR 权限)。
- 目标技能已登记在
skills-lock.json中并带有 source。未登记、source 缺失、lock 不存在或解析失败时,脚本会在 clone 之前中止。新技能的首次贡献不在本技能范围内。 - 目标技能目录下的内容与最新提交一致。存在未提交变更、未跟踪文件或 ignore 对象文件时,脚本会在 clone 之前中止。目标技能以外的位置发生的变更不会被检查。
主要流程
Step 1:校验参数
- 若参数为空,则不进行路径解析,列出
skills/、.agents/skills/、.claude/skills/(仅实际目录,symlink 会在实体侧候选中出现,因此排除)的候选列表后退出。 - 对技能名进行 kebab-case 校验(防止路径穿越),在路径解析之前执行。
- 若环境变量
LOCAL_SKILL_DIR已设置,则校验其是否为允许的三个路径之一、路径的所有元素(含中间父目录)均非 symlink、且实际存在,然后采用并跳过自动解析。 - 自动解析时,若
skills/、.agents/skills/、.claude/skills/中存在多个实体目录,则中止,并提示通过环境变量LOCAL_SKILL_DIR指定改修对象路径后重新执行(不会静默优先选择skills/)。
Step 2:确定 upstream
- 读取根目录的
skills-lock.json,取出skills.<SKILL_NAME>.source。 - 未登记或 source 缺失时 fail-closed 中止。
- 安全阀:拒绝向 Fandhe-AI org 以外的仓库 push。先做规范化(URL 形式转换为 OWNER/REPO,短形式直接采用),去除末尾
.git,再进行严格校验:owner 固定为 Fandhe-AI,repo 仅允许单段[A-Za-z0-9._-]+。 - 含
../的路径穿越、查询(?x=1)、片段(#frag)、多余路径段(/extra)等值均不匹配正则,会报错中止。 sourceType非 github 时也报错中止。- 规范化后的
REPO_SLUG会在后续步骤中用于gh repo clone与gh pr create --repo。
Step 3:确认变更内容
- 先确认复制来源与 HEAD 一致。使用
git status --porcelain=v1 --untracked-files=all --ignored检查目标目录,非零退出或存在输出时中止。 - 显示
git log --oneline与git diff(无父提交时与空树比较)。 - 检查中止时,Claude 不会自动 stash、删除或提交,而是向用户展示列出的路径,由用户选择处理方式(提交或移除)后重新执行。
- 向用户确认「是否以此改修内容向上游创建 PR」。
Step 4:安全检查(必须)
与 create-pr 相同,审查以下内容:
- 认证、授权实现遗漏
- API 密钥、机密信息的硬编码
- XSS 可能性(文档中若含外部嵌入)
- 输入校验缺失
- OWASP Top 10
发现问题时中止上游贡献并向用户告警。
Step 5:反映变更
skills-contribute.sh自行完成从 upstream 的gh repo clone到工作目录(WORKDIR)创建与反映的全过程,无需手动预先 clone。- 本步骤必须执行本技能自身的脚本
skills-contribute.sh,不要单独逐条执行片段。该脚本内置了rm -rf前的 symlink 边界校验(含 TOCTOU 对策)。 - 脚本内部判定 upstream 侧技能所处的路径结构(
UPSTREAM_SKILL_PATH;skills-lock.json的skillPath是本地 install 路径,并非 upstream 内配置,因此不使用),并执行cp -R的 delete-then-copy 反映。 LOCAL_SKILL_DIR是 Step 1 解析出的贡献对象技能路径,与本技能(contribute-skill)自身的配置无关。执行脚本自身的配置应通过另一变量CONTRIBUTE_SKILL_DIR,从本技能自身的安装位置解析。- 脚本以调用时的当前目录作为贡献源仓库根目录,探索
LOCAL_SKILL_DIR与skills-lock.json,并在内部新建自身的gh repo clone与 WORKDIR。执行前需在本步骤内捕获ORIG_DIR(贡献源本地仓库根目录)。 - 捕获脚本标准输出最后几行返回的
CONTRIBUTE_SKILL_WORKDIR=<path>与CONTRIBUTE_SKILL_UPSTREAM_PATH=<path>,后续步骤中${WORKDIR}/upstream与${UPSTREAM_SKILL_PATH}仅以这些值为唯一准绳。 - 获取默认分支(用于 Step 8 的
gh pr create --base)。origin/HEAD未设置时symbolic-ref会非零退出,因此用|| true吸收。
适用场景
- 在本地改修了某个已登记技能目录,希望将其作为 PR 提交回上游 Fandhe-AI 组织下的仓库。
- 需要与当前仓库内的 create-pr 区分开,面向外部仓库进行贡献。
限制
- 仅支持向 Fandhe-AI org 下的仓库 push,其他 org 会被安全阀拒绝。
- 仅支持
sourceType为 github 的 source。 - 新技能的首次贡献不在本技能范围内。
- 目标技能必须已登记在
skills-lock.json中且带有 source。 - 目标技能目录必须与最新提交一致,存在未提交、未跟踪或 ignore 对象文件时会中止。
- 关于收费、价格、平台支持范围、具体效果等,资料中暂未提供。