Locally modified skills/<skill-name>/ を、skills-lock.json is submitted as a PR to the upstream repository recorded in .
Prerequisites
ghThe CLI is installed and authenticated (push / PR permissions to the target org are required)- The target skill is registered in
skills-lock.jsonand hassource(if unregistered,sourcemissing, lock absent, or parsing fails, the script aborts before clone. Initial contributions of new skills are out of scope) - The contents under the target skill's directory match the latest commit (if there are uncommitted changes, untracked files, or ignored files, the script aborts before clone. Changes in locations other than the target skill are not inspected)
Separation of responsibilities
- create-pr: Creates a PR from the current branch to base within the current repository
- contribute-skill: Performs clone → apply changes → push → create PR to a separate repository (upstream)
External repository contributions involve clone / path conversion / different authentication boundaries, so they are separated as a distinct skill.
Flow
Step 1: Validate the arguments
SKILL_NAME="$ARGUMENTS"
# 空判定ガード: パス解決の前に SKILL_NAME を確定させる
if [[ -z "${SKILL_NAME}" ]]; then
echo "対象スキルを指定してください。候補:"
ls -1 skills/ 2>/dev/null
ls -1 .agents/skills/ 2>/dev/null
# .claude/skills/ は skills/ への symlink 慣習と実体配置(例: create-skill / create-agent)が
# 併存するため、実ディレクトリのみ列挙する(symlink は実体が上の 2 候補に現れる)。
# 親の .claude / .claude/skills 自体が symlink の場合も配下の実体は symlink 先で列挙されるため、
# 経路の全親が symlink でないときのみ find する(-type d は親 symlink 経由でも列挙してしまう)
[[ ! -L .claude && ! -L .claude/skills ]] && find .claude/skills -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sed 's|.*/||'
echo "(lockfile 由来のスキルは .agents/skills/ のみ、リポジトリ管理スキルは .claude/skills/ のみに存在する場合がある)"
exit 1 # ユーザーが選んだスキル名を引数に付けて再実行する
fi
# kebab-case 検証(パストラバーサル防止): パス解決より前に実施する
if [[ ! "${SKILL_NAME}" =~ ^[a-z][a-z0-9-]+$ ]]; then
echo "エラー: SKILL_NAME は小文字 kebab-case のみ許可されています: ${SKILL_NAME}"
exit 1
fi
# symlink 境界の共通判定(fail-closed): 相対経路 rel の全要素を先頭から累積検査し、
# いずれかが symlink なら該当パスを SYMLINK_COMPONENT に設定して 1 を返す。
# 第2引数 base を与えると base 配下の相対経路として検査する(省略時はカレント基準)。
# 末尾要素だけの -L 検査では親(例: .claude 自体がリポジトリ外を指す symlink)を
# すり抜けるため、候補判定・override 検証・upstream 配置判定・rm 前検証の
# すべての経路判定でこの関数を使い「どの経路要素が symlink でも候補と数えない」を一貫させる。
assert_no_symlink_components() {
local rel="$1" prefix="${2:+${2}/}" acc="" part
local -a parts
SYMLINK_COMPONENT=""
IFS='/' read -r -a parts <<< "${rel}"
for part in "${parts[@]}"; do
acc="${acc:+${acc}/}${part}"
if [[ -L "${prefix}${acc}" ]]; then
SYMLINK_COMPONENT="${prefix}${acc}"
return 1
fi
done
return 0
}
# override: 環境変数 LOCAL_SKILL_DIR が設定済みならそれを検証して使う
if [[ -n "${LOCAL_SKILL_DIR:-}" ]]; then
case "${LOCAL_SKILL_DIR}" in
"skills/${SKILL_NAME}"|".agents/skills/${SKILL_NAME}"|".claude/skills/${SKILL_NAME}") ;;
*)
echo "エラー: LOCAL_SKILL_DIR は skills/${SKILL_NAME} / .agents/skills/${SKILL_NAME} / .claude/skills/${SKILL_NAME} のいずれかを指定してください: ${LOCAL_SKILL_DIR}"
exit 1
;;
esac
# symlink(.claude/skills/<name> → skills/<name> 慣習)は差分表示が空になるため実体側を要求する。
# 末尾要素だけでなく全中間要素(例: .claude → .claude/skills)も累積検査し、
# 親ディレクトリが symlink のパス指定も fail-closed で拒否する(自動解決側と同一関数で対称)
if ! assert_no_symlink_components "${LOCAL_SKILL_DIR}"; then
echo "エラー: LOCAL_SKILL_DIR の経路に symlink が含まれています。実体側のパスを指定してください: ${SYMLINK_COMPONENT} -> $(readlink "${SYMLINK_COMPONENT}")"
exit 1
fi
if [[ ! -d "${LOCAL_SKILL_DIR}" ]]; then
echo "エラー: 指定された LOCAL_SKILL_DIR が存在しません: ${LOCAL_SKILL_DIR}"
exit 1
fi
else
# 自動解決(複数存在する場合は中止して override を促す)
have_skills=0; have_agents=0; have_claude=0
# 各候補は経路の全要素(.claude 等の最上位親を含む)が実体の場合のみ数える。
# symlink 経由の候補は実体側候補で検出されるため数えず(重複カウント防止)、
# .claude 自体がリポジトリ外を指す symlink の場合も候補と数えない(fail-closed)
[[ -d "skills/${SKILL_NAME}" ]] && assert_no_symlink_components "skills/${SKILL_NAME}" && have_skills=1
[[ -d ".agents/skills/${SKILL_NAME}" ]] && assert_no_symlink_components ".agents/skills/${SKILL_NAME}" && have_agents=1
[[ -d ".claude/skills/${SKILL_NAME}" ]] && assert_no_symlink_components ".claude/skills/${SKILL_NAME}" && have_claude=1
if (( have_skills + have_agents + have_claude > 1 )); then
echo "エラー: ${SKILL_NAME} の実体が skills/ / .agents/skills/ / .claude/skills/ の複数に存在します。"
echo "環境変数 LOCAL_SKILL_DIR にどれかを指定して再実行してください(例: LOCAL_SKILL_DIR=.agents/skills/${SKILL_NAME})。"
exit 1
elif [[ "${have_skills}" -eq 1 ]]; then
LOCAL_SKILL_DIR="skills/${SKILL_NAME}"
elif [[ "${have_agents}" -eq 1 ]]; then
LOCAL_SKILL_DIR=".agents/skills/${SKILL_NAME}"
elif [[ "${have_claude}" -eq 1 ]]; then
LOCAL_SKILL_DIR=".claude/skills/${SKILL_NAME}"
else
echo "エラー: ローカルスキルが見つかりません: skills/${SKILL_NAME} / .agents/skills/${SKILL_NAME} / .claude/skills/${SKILL_NAME}"
exit 1
fi
fi
If the argument is empty, do not proceed to path resolution; display the candidate list ofskills/・.agents/skills/・.claude/skills/(real directories only. Symlinks are excluded because they appear as candidates on the target side) and exit. Claude should present that list to the user, have them choose a skill name, and prompt them to re-run. In subsequent Steps, use ${LOCAL_SKILL_DIR}/ to reference the local path.
skills/・.agents/skills/・.claude/skills/(real directories only. Symlinks are counted on the target side) ofAbort if directories exist in multiplelocations, and instruct the user to specify the path to be modified ( LOCAL_SKILL_DIR in the environment variableskills/<name>・.agents/skills/<name>・.claude/skills/<name> one of) and re-run (do not silently prioritize skills/ ). If the environment variable LOCAL_SKILL_DIR is already set, verify that it is one of the three permitted paths, that all elements of the path (including intermediate parent directories) are not symlinks, and that it actually exists, then adopt it and skip automatic resolution. If it exists in none of them, abort with an error.
Step 2: Identify the upstream
Route's skills-lock.json reads, and extractsskills.<SKILL_NAME>.source .
# jq が使えるなら jq で取得する
SOURCE=$(jq -r --arg n "${SKILL_NAME}" '.skills[$n].source // empty' skills-lock.json) || { echo "エラー: skills-lock.json を解析できません。中止します。"; exit 1; }
SOURCE_TYPE=$(jq -r --arg n "${SKILL_NAME}" '.skills[$n].sourceType // empty' skills-lock.json) || SOURCE_TYPE=""
# 未登録・source 欠落は fail-closed(スクリプトと同じ判定)
if [[ -z "${SOURCE}" ]]; then
echo "エラー: スキル '${SKILL_NAME}' が skills-lock.json に未登録、または source がありません。中止します。"
exit 1
fi
# 安全弁: Fandhe-AI org 以外への push を拒否する
# 1) まず正規化する(URL 形式は OWNER/REPO へ変換、短縮形はそのまま採用)
case "${SOURCE}" in
https://github.com/*)
REPO_SLUG="${SOURCE#https://github.com/}"
;;
*)
REPO_SLUG="${SOURCE}"
;;
esac
# 末尾 .git の除去は両形式共通で行う
# (URL 分岐内のみで除去すると短縮形 'Fandhe-AI/<repo>.git' が .git 付きのまま
# 後段の正規表現を通過してしまうため、検証の前に必ずここで正規化する)
REPO_SLUG="${REPO_SLUG%.git}"
# 2) 正規化後の値を厳密検証する: owner は Fandhe-AI 固定、repo は単一セグメントのみ許可する
# [A-Za-z0-9._-]+ は '/'・'?'・'#'・空文字を含められないため、
# パストラバーサル(../)・余剰パスセグメント・クエリ・フラグメントをすべて拒否できる
# (前方一致では `Fandhe-AI/../../attacker/repo` のような値が通過するため)
if [[ ! "${REPO_SLUG}" =~ ^Fandhe-AI/[A-Za-z0-9._-]+$ ]]; then
echo "エラー: source '${SOURCE}' は Fandhe-AI/<repo> 形式ではありません。中止します。"
exit 1
fi
# 3) '.'・'..' は上記正規表現を通過してしまうため repo 名として明示拒否する
# (例: 'Fandhe-AI/..git' は .git 除去後に 'Fandhe-AI/.' へ化ける)
case "${REPO_SLUG#Fandhe-AI/}" in
.|..)
echo "エラー: source '${SOURCE}' の repository 名が不正です。中止します。"
exit 1
;;
esac
# sourceType が github 以外なら中止(GitHub 以外の source は本スキルの想定外)
if [[ "${SOURCE_TYPE}" != "github" ]]; then
echo "エラー: sourceType '${SOURCE_TYPE}' は github ではありません。中止します。"
exit 1
fi
sourceis permitted only when it exactly matches the normalizedOWNER/REPOが^Fandhe-AI/[A-Za-z0-9._-]+$(safety valve: to avoid unintentionally pushing to an unknown repository).../Values containing path traversal, queries (?x=1)・Fragment (#frag), or extra path segments (/extra) do not match the regular expression and abort with an error. Validation must always be performed.gitafternormalization such as removing(validating before normalization causesFandhe-AI/..git(because such a value changes into a different value after normalization and slips through).sourceTypeがgithubif it is other than abort with an error (sources other than GitHub are outside the assumptions of this skill, andgh repo clone/gh pr createdoes not work correctly).- After normalization,
REPO_SLUGis used in subsequent Steps asgh repo clone・gh pr create --repo.
Step 3: Check the changes
# コピー元が HEAD と一致することを先に確認する(強制点は skills-contribute.sh 側。
# --untracked-files=all を省くと status.showUntrackedFiles=no で未追跡が隠れ、--ignored を
# 省くと .env 等の ignore 対象が見逃される。非ゼロ終了も clean と扱わず中止する)
rc=0; DIRTY=$(git status --porcelain=v1 --untracked-files=all --ignored -- "${LOCAL_SKILL_DIR}") || rc=$?
if [[ "${rc}" -ne 0 || -n "${DIRTY}" ]]; then
echo "中止: ${LOCAL_SKILL_DIR} が HEAD と一致しないか、状態を確認できません" >&2
printf '%s\n' "${DIRTY}" >&2
exit 1
fi
git log --oneline -- "${LOCAL_SKILL_DIR}/"
# HEAD~1 の有無を明示的に判定する(git diff は差分ありでも終了コード 0 のため || で分岐しない)
if git rev-parse --verify -q HEAD~1 >/dev/null; then
git diff HEAD~1 HEAD -- "${LOCAL_SKILL_DIR}/"
else
# 親コミットがない場合(初回コミット・shallow clone 等)は空ツリーと HEAD を比較する
# (作業ツリー差分ではコミット済み・クリーンな状態で空になるため使わない)
git diff "$(git hash-object -t tree /dev/null)" HEAD -- "${LOCAL_SKILL_DIR}/"
fi
If the inspection aborts the process, Claude does not automatically stash, delete, or commit. Present the listed paths to the user, have them choose how to handle them (commit / remove), and then run it again.
Ask the user to confirm "Is it OK to create a PR to upstream with these changes?".
Step 4: Security check (required)
create-pr Review the following in the same way as for
- Missing authentication/authorization implementation
- Hardcoding API keys and secrets
- Possibility of XSS (even for documents, if external embedding is included)
- Lack of input validation
- OWASP Top 10
If there is a problem, stop the upstream contribution and warn the user.
Step 5: Apply the changes
skills-contribute.sh は upstream の gh repo clone fromWORKDIRto the creation and application of the working directory (CONTRIBUTE_SKILL_WORKDIR= , etc.) as the sole source of truth.
For this step, do not type the procedure individually; be sure to execute this skill's own script (skills-contribute.sh). The same script implements symlink boundary validation before rm -rf (including TOCTOU countermeasures), and if only the following fragments are executed individually, the validation will be missing.
skills-contribute.sh is a self-contained script that internally performs the determination of which path structure the skill is placed under on the upstream side (UPSTREAM_SKILL_PATH。skills-lock.json の skillPath is the local install path and is not used because it is not the placement within upstream) and the delete-then-copy application ofcp -R . The logic for determination and application is as in the reference code described later.
LOCAL_SKILL_DIR is the path of thecontribution target skill($ARGUMENTSresolved in Step 1, and is unrelated to the placement of this skill (contribute-skill) itself. If LOCAL_SKILL_DIR is reused for the script execution path, then when the contribution target is other than contribute-skill, it will reference a path that does not exist. Resolve the placement of the script itself to be executed as a separate variable CONTRIBUTE_SKILL_DIR from the installation location of this skill (contribute-skill) itself.
skills-contribute.sh searches for LOCAL_SKILL_DIR・skills-lock.json using the current directory at call time as the root of the contribution source repository, and internally creates its own new gh repo clone と WORKDIR(clone destination). Immediately before execution, capture ORIG_DIR(the root of the contribution source local repository) within this Step. Capture the CONTRIBUTE_SKILL_WORKDIR=<path> と CONTRIBUTE_SKILL_UPSTREAM_PATH=<path> returned by the final lines of the script's standard output, andWORKDIR and (the determination logic shown in the reference code below)UPSTREAM_SKILL_PATH adopt only these values as the sole source of truth (values obtained by running the reference code individually are not used). As a result, the ${WORKDIR}/upstream と ${UPSTREAM_SKILL_PATH} referenced from Step 6 onward matches the clone actually used by the script and the paths actually applied.
# cd する前にローカルリポジトリのルートを捕捉する(cd - は stdout を汚染するため使用しない)
ORIG_DIR="$(pwd)"
# 本スキル自身(contribute-skill)の配置を ORIG_DIR 基準の絶対パスで解決する。
# LOCAL_SKILL_DIR(貢献対象)とは別物。
# override: 環境変数 CONTRIBUTE_SKILL_DIR が設定済みならそれを検証して使う
if [[ -n "${CONTRIBUTE_SKILL_DIR:-}" ]]; then
# 完全一致判定で3候補それぞれの固定相対パス文字列リテラルを選ぶ。
# ${VAR#pattern} 等のパラメータ展開によるプレフィックス除去は使わない
# (ORIG_DIR に [ * ? 等の glob 文字が含まれると pattern として解釈され、
# 接頭辞を除去し切れず絶対パスのまま検査関数へ渡ってしまうため)。
if [[ "${CONTRIBUTE_SKILL_DIR}" == "${ORIG_DIR}/skills/contribute-skill" ]]; then
CONTRIBUTE_SKILL_REL="skills/contribute-skill"
elif [[ "${CONTRIBUTE_SKILL_DIR}" == "${ORIG_DIR}/.agents/skills/contribute-skill" ]]; then
CONTRIBUTE_SKILL_REL=".agents/skills/contribute-skill"
elif [[ "${CONTRIBUTE_SKILL_DIR}" == "${ORIG_DIR}/.claude/skills/contribute-skill" ]]; then
CONTRIBUTE_SKILL_REL=".claude/skills/contribute-skill"
else
echo "エラー: CONTRIBUTE_SKILL_DIR は ${ORIG_DIR}/skills/contribute-skill / ${ORIG_DIR}/.agents/skills/contribute-skill / ${ORIG_DIR}/.claude/skills/contribute-skill のいずれかを指定してください: ${CONTRIBUTE_SKILL_DIR}"
exit 1
fi
# LOCAL_SKILL_DIR と同じ fail-closed 方針: 末尾要素・中間の親ディレクトリのいずれかが
# symlink の場合は実体側パスの指定を要求する(assert_no_symlink_components は Step 1 で定義済み)。
# 上記で完全一致判定した固定相対パスリテラル(CONTRIBUTE_SKILL_REL)を検査関数へ渡す。
if ! assert_no_symlink_components "${CONTRIBUTE_SKILL_REL}" "${ORIG_DIR}"; then
echo "エラー: CONTRIBUTE_SKILL_DIR の経路に symlink が含まれています。実体側のパスを指定してください: ${SYMLINK_COMPONENT} -> $(readlink "${SYMLINK_COMPONENT}")"
exit 1
fi
if [[ ! -d "${CONTRIBUTE_SKILL_DIR}" ]]; then
echo "エラー: 指定された CONTRIBUTE_SKILL_DIR が存在しません: ${CONTRIBUTE_SKILL_DIR}"
exit 1
fi
else
# 自動解決。Step 1 の LOCAL_SKILL_DIR 解決と同じ fail-closed 方針: 複数存在する場合は
# どれを使うべきか判断できないため中止する(silently に skills/ を優先しない)。
# 各候補は経路の全要素(.claude 等の最上位親を含む)が実体の場合のみ数える
# (symlink 経由の候補は実体側候補で検出されるため重複カウントしない)。
have_contribute_skills=0; have_contribute_agents=0; have_contribute_claude=0
[[ -d "${ORIG_DIR}/skills/contribute-skill" ]] && assert_no_symlink_components "skills/contribute-skill" "${ORIG_DIR}" && have_contribute_skills=1
[[ -d "${ORIG_DIR}/.agents/skills/contribute-skill" ]] && assert_no_symlink_components ".agents/skills/contribute-skill" "${ORIG_DIR}" && have_contribute_agents=1
[[ -d "${ORIG_DIR}/.claude/skills/contribute-skill" ]] && assert_no_symlink_components ".claude/skills/contribute-skill" "${ORIG_DIR}" && have_contribute_claude=1
if (( have_contribute_skills + have_contribute_agents + have_contribute_claude > 1 )); then
echo "エラー: contribute-skill の実体が ${ORIG_DIR}/skills/contribute-skill / ${ORIG_DIR}/.agents/skills/contribute-skill / ${ORIG_DIR}/.claude/skills/contribute-skill の複数に存在します。"
echo "環境変数 CONTRIBUTE_SKILL_DIR にどれかを指定して再実行してください(例: CONTRIBUTE_SKILL_DIR=${ORIG_DIR}/.agents/skills/contribute-skill)。"
exit 1
elif [[ "${have_contribute_skills}" -eq 1 ]]; then
CONTRIBUTE_SKILL_DIR="${ORIG_DIR}/skills/contribute-skill"
elif [[ "${have_contribute_agents}" -eq 1 ]]; then
CONTRIBUTE_SKILL_DIR="${ORIG_DIR}/.agents/skills/contribute-skill"
elif [[ "${have_contribute_claude}" -eq 1 ]]; then
CONTRIBUTE_SKILL_DIR="${ORIG_DIR}/.claude/skills/contribute-skill"
else
echo "エラー: contribute-skill 自身の配置が見つかりません(${ORIG_DIR}/skills/contribute-skill / ${ORIG_DIR}/.agents/skills/contribute-skill / ${ORIG_DIR}/.claude/skills/contribute-skill)。"
exit 1
fi
fi
# skills-contribute.sh は自分自身で clone するため、呼び出し前に必ずローカルリポジトリ
# ルートへ cd し直す。LOCAL_SKILL_DIR は通常の変数代入では子プロセスへ継承されない
# (export されていない)ため明示的に渡す。標準出力はそのまま表示しつつ変数へも捕捉する。
cd "${ORIG_DIR}"
SCRIPT_OUTPUT=$(LOCAL_SKILL_DIR="${LOCAL_SKILL_DIR}" "${CONTRIBUTE_SKILL_DIR}/scripts/skills-contribute.sh" "${SKILL_NAME}" "${REPO_SLUG}" | tee /dev/stderr)
# スクリプトが実際に使った作業 clone・upstream スキルパスを Step 6 以降の唯一の正として採用する。
# 以下の参考コードで計算され得る UPSTREAM_SKILL_PATH はこの値で上書きする。
# 以降 "${WORKDIR}/upstream" は常にスクリプトが cp -R でコピーした clone を、
# "${UPSTREAM_SKILL_PATH}" は常にスクリプトが実際に反映したパスを指す。
SCRIPT_UPSTREAM_DIR=$(echo "${SCRIPT_OUTPUT}" | grep '^CONTRIBUTE_SKILL_WORKDIR=' | tail -1 | cut -d= -f2-)
UPSTREAM_SKILL_PATH=$(echo "${SCRIPT_OUTPUT}" | grep '^CONTRIBUTE_SKILL_UPSTREAM_PATH=' | tail -1 | cut -d= -f2-)
if [[ -z "${SCRIPT_UPSTREAM_DIR}" || ! -d "${SCRIPT_UPSTREAM_DIR}" ]]; then
echo "エラー: skills-contribute.sh の出力から作業ディレクトリ(CONTRIBUTE_SKILL_WORKDIR)を取得できませんでした。"
exit 1
fi
if [[ -z "${UPSTREAM_SKILL_PATH}" ]]; then
echo "エラー: skills-contribute.sh の出力から upstream スキルパス(CONTRIBUTE_SKILL_UPSTREAM_PATH)を取得できませんでした。"
exit 1
fi
WORKDIR="$(dirname "${SCRIPT_UPSTREAM_DIR}")"
cd "${SCRIPT_UPSTREAM_DIR}"
# デフォルトブランチを取得する(Step 8 の gh pr create --base で使用)。
# origin/HEAD 未設定時に symbolic-ref が非ゼロ終了する。set -e 下(本コマンドを
# skills-contribute.sh 同様の厳格モードで実行する場合)では ${DEFAULT_BRANCH:-main}
# フォールバックへ到達できなくなるため `|| true` で吸収する
# (skills-contribute.sh の同じ処理と同じ理由)。
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||' || true)
echo "デフォルトブランチ: ${DEFAULT_BRANCH:-main}"
Below is the reference code for the processing that skills-contribute.sh executes internally (theUPSTREAM_SKILL_PATH determination and delete-then-copy). Since it has already been completed by the above script execution, there is no need to run it individually.
# upstream のスキル配置はクローンしたリポジトリのレイアウトで判定する
# (skills-lock.json の skillPath はローカル install パスであり upstream の配置ではないため使わない)
# 各候補は assert_no_symlink_components(Step 1 で定義した共通判定)で経路の全要素が
# 実体の場合のみ採用する。clone 内に symlink(例: .claude がリポジトリ外を指す)が
# 含まれていても、その経路をコピー先と数えず fail-closed で次候補へフォールバックする
if [[ -d "skills/${SKILL_NAME}" ]] && assert_no_symlink_components "skills/${SKILL_NAME}"; then
UPSTREAM_SKILL_PATH="skills/${SKILL_NAME}"
elif [[ -d ".agents/skills/${SKILL_NAME}" ]] && assert_no_symlink_components ".agents/skills/${SKILL_NAME}"; then
UPSTREAM_SKILL_PATH=".agents/skills/${SKILL_NAME}"
elif [[ -d ".claude/skills/${SKILL_NAME}" ]] && assert_no_symlink_components ".claude/skills/${SKILL_NAME}"; then
# upstream が .claude/skills/ 配下に実体を置いている慣習(例: create-skill / create-agent)。
# .claude/skills/<name> は skills/<name> への symlink 慣習も併存するため、
# 経路のどこかが symlink の場合は採用しない
# (symlink の場合は解決先の実体が上の 2 分岐で検出される)
UPSTREAM_SKILL_PATH=".claude/skills/${SKILL_NAME}"
elif [[ -d "skills" ]] && assert_no_symlink_components "skills"; then
# upstream が skills/ 配下で公開している慣習
UPSTREAM_SKILL_PATH="skills/${SKILL_NAME}"
elif [[ -d ".agents/skills" ]] && assert_no_symlink_components ".agents/skills"; then
# upstream が .agents/skills/ 配下で公開している慣習
UPSTREAM_SKILL_PATH=".agents/skills/${SKILL_NAME}"
elif [[ -d ".claude/skills" ]] && assert_no_symlink_components ".claude/skills"; then
# upstream が .claude/skills/ を実体スキルルートとして公開している慣習。
# 新規スキル(upstream にまだ存在しない)は上の個別パス判定に掛からないため、
# 親ディレクトリの存在で判定する。.claude / .claude/skills が symlink の場合は
# 実体側ルートが上の skills/ / .agents/skills/ 分岐で検出されるため採用しない
UPSTREAM_SKILL_PATH=".claude/skills/${SKILL_NAME}"
else
echo "警告: upstream にスキルルートが見つかりません。skills/ を既定として新規追加します。"
UPSTREAM_SKILL_PATH="skills/${SKILL_NAME}"
fi
# 削除伝搬のための同期: cp -R は削除を反映しないため、宛先を消してからコピーする
# 安全弁1: 削除対象が clone 内の想定スキルパス(3 形態のみ)であることを検証してから rm する
case "${UPSTREAM_SKILL_PATH}" in
"skills/${SKILL_NAME}"|".agents/skills/${SKILL_NAME}"|".claude/skills/${SKILL_NAME}") ;;
*)
echo "エラー: 想定外の UPSTREAM_SKILL_PATH です: ${UPSTREAM_SKILL_PATH}"
exit 1
;;
esac
# 安全弁2: 実体パスでの symlink 境界検証(fail-closed)。安全弁1 の case allowlist は
# 文字列形式のみの検証であり、clone 内の中間ディレクトリ(skills / .agents 等)が
# 実行中に symlink へ差し替えられた場合には対応できないため、rm -rf の直前に
# 以下を実体パスで再確認する(詳細な実装は scripts/skills-contribute.sh を参照)。
# (a) clone ルートから削除対象までの各中間パス要素が symlink でないこと
# (b) 削除対象の親ディレクトリの正規パス(pwd -P)が clone ルート配下であること
# (c) 検証と削除の間の TOCTOU を閉じるため、検証済みの親ディレクトリへ cd -P した
# cwd に対して相対パスで rm する(パス文字列を再解決しない)
# いずれかに違反する場合は削除を実行せずエラー終了する。
CLONE_ROOT="${WORKDIR}/upstream"
DELETE_TARGET="${CLONE_ROOT}/${UPSTREAM_SKILL_PATH}"
CLONE_ROOT_REAL="$(cd "${CLONE_ROOT}" && pwd -P)"
if ! assert_no_symlink_components "${UPSTREAM_SKILL_PATH}" "${CLONE_ROOT}"; then
echo "エラー: 削除対象の経路に symlink が含まれています: ${SYMLINK_COMPONENT}"
exit 1
fi
DELETE_PARENT="$(dirname "${DELETE_TARGET}")"
DELETE_LEAF="$(basename "${DELETE_TARGET}")"
if [[ -d "${DELETE_PARENT}" ]]; then
(
cd -P -- "${DELETE_PARENT}" || exit 1
PARENT_REAL="$(pwd -P)"
case "${PARENT_REAL}/" in
"${CLONE_ROOT_REAL}/"*) ;;
*)
echo "エラー: 削除対象の親ディレクトリが clone ルート配下ではありません: ${PARENT_REAL}"
exit 1
;;
esac
rm -rf -- "${DELETE_LEAF}"
)
fi
# スクリプトはここで貢献元の対象スキルを再検査する(clone を挟む間の変更を拾うため。
# 未コミット・未追跡・ignore 対象があれば中止し、コピーしない)
mkdir -p "${WORKDIR}/upstream/${UPSTREAM_SKILL_PATH}"
# LOCAL_SKILL_DIR は Step 1 で解決済み(skills/<name>/ または .agents/skills/<name>/)
# ORIG_DIR は Step 5 で cd する前に捕捉済み(cd - は stdout 汚染のため使用しない)
cp -R "${ORIG_DIR}/${LOCAL_SKILL_DIR}/." "${WORKDIR}/upstream/${UPSTREAM_SKILL_PATH}/"
The deletion target is always confined under ${WORKDIR}/upstream/ (the temporary directory for cloning), and if it is not one of the 3 forms ofUPSTREAM_SKILL_PATH が skills/<name>・.agents/skills/<name>・.claude/skills/<name> , it aborts before rm -rf . In addition, immediately before rm, it verifies the real path against symlinking of intermediate paths and TOCTOU. Even in the case of adding a new skill (destination does not exist), the deletion process is harmlessly skipped and it is created by the immediately following mkdir -p .
Step 6: Check the diff
cd "$WORKDIR/upstream"
git status
git diff
Show the diff to the user and confirm that the content is as intended.
Step 7: Create branch and commit
SLUG=$(date +%Y%m%d-%H%M%S)
git switch -c "contribute/${SKILL_NAME}-${SLUG}"
git add "${UPSTREAM_SKILL_PATH}/"
git commit -m "$(cat <<'EOF'
<type>(<scope>): <subject>
ローカルの skills/<SKILL_NAME>/ からの貢献。
EOF
)"
git add "${UPSTREAM_SKILL_PATH}/"uses path-specified add, so deletions of files removed by the delete-then-copy in Step 5 (D) are also staged- Conventional Commits format
--no-verifyis not used (allow pre-commit hooks to run)- Do not add co-author (align with local conventions)
Step 8: push and create PR
git push -u origin "contribute/${SKILL_NAME}-${SLUG}"
# 貢献元リポジトリの OWNER/REPO を取得する(PR body の Source 節に使用。
# 本スキルは任意のリポジトリから実行されるため、特定リポジトリ名を固定しない)
SRC_REPO=$(git -C "${ORIG_DIR}" remote get-url origin 2>/dev/null \
| sed -E 's#^(git@github\.com:|https://github\.com/)##; s#\.git$##')
[[ -n "${SRC_REPO}" ]] || SRC_REPO=$(basename "${ORIG_DIR}")
gh pr create \
--repo "${REPO_SLUG}" \
--base "${DEFAULT_BRANCH:-main}" \
--title "<type>(<scope>): <subject>" \
--body "$(cat <<'EOF'
## Summary
- <SKILL_NAME> の改修内容(箇条書き)
## Source
ローカルの <SRC_REPO> 側で改修後、`/contribute-skill <SKILL_NAME>` により投稿。
## Test plan
- [ ] SKILL.md を実際に Claude Code で実行
- [ ] Conventional Commits に沿ったメッセージ生成を確認
- [ ] エッジケース確認
EOF
)"
--repo is passed the ${REPO_SLUG}(OWNER/REPO normalized in Step 2). Conversion from URL format to OWNER/REPO has already been completed by the case statement in Step 2.
body の <SRC_REPO> is replaced with the OWNER/REPOof the contributing source repository obtained above (or the directory name if origin is not set) (the heredoc is quoted, so Claude fills in the actual value. Hardcoding a specific repository name is prohibited).
When creating a Draft PR, add --draft (the default is decided after user confirmation).
Step 9: Return the PR URL & post-processing guidance
- Return the PR URL to the user
- "Once merged,
/sync-skills-lockand instruct them to runskills-lock.jsonのcomputedHashto update - Leave the working directory
$WORKDIRin place (until success or failure is determined)
Notes
- SKILL_NAME allows only kebab-case:
..To prevent path traversal via values such as^[a-z][a-z0-9-]+$immediately after the empty check and before path resolution (OWASP A03 / A01) skills/・.agents/skills/・.claude/skills/Abort if entities exist in multiple of:silently にskills/Do not prioritizeLOCAL_SKILL_DIR, and request re-execution by specifying the path to be modified in the environment variableLOCAL_SKILL_DIRはskills/<name>・.agents/skills/<name>・.claude/skills/<name>(if either the last element or an intermediate parent directory is a symlink, request specification of the real path), preventing path traversal via arbitrary path specification. In Step 5, resolve the placement of this skill itself (contribute-skill)CONTRIBUTE_SKILL_DIRalso takes the same fail-closed policy, and${ORIG_DIR}/skills/contribute-skill・${ORIG_DIR}/.agents/skills/contribute-skill・${ORIG_DIR}/.claude/skills/contribute-skillaccepts only these 3 candidates (if either the trailing element or an intermediate parent directory is a symlink, the real-side path must be specified). If more than one of the 3 candidates exists, do not silently prioritize one; abort and require specification via the environment variableCONTRIBUTE_SKILL_DIR(do not make this asymmetric with LOCAL_SKILL_DIR)- if the source is other than the Fandhe-AI org, abort: not by prefix match (
Fandhe-AI/*etc.), but by exact match against the.gitafter normalization (removal ofOWNER/REPOが^Fandhe-AI/[A-Za-z0-9._-]+$etc.).../values containing path traversal, queries, fragments, or extra path segments via./.., and values where the repo name becomes - lock absent, unregistered,
sourcemissing, or lock parse failure is fail-closed: abort before clone (do not skip verification and continue). The first contribution of a new skill is out of scope for this skill - if a security issue is found, abort: rerun after fixing
- upstream placement is determined by the layout of the cloned repository:
skills-lock.jsonのskillPathis the local install path (e.g.,.agents/skills/github-docs/SKILL.md), and is not the placement within the upstream repository.skillPathの dirname をUPSTREAM_SKILL_PATHmust not be adopted. The determination order is the existence ofskills/<name>→ the existence of.agents/skills/<name>→ the existence of.claude/skills/<name>→ the convention of the skill root's parent directory (skills/→.agents/skills/→.claude/skills/order. For a new skill, since an individual path does not exist, the placement destination is decided by this parent directory determination) → the final defaultskills/(the more general public layout). For all candidates, adopt only if every element of the path (assert_no_symlink_componentsvia.claudeincluding the topmost parent such as.claudeis not a symlink, and even if - copy the destination after deleting it (deletion propagation):
cp -Ronly adds and overwrites and does not reflect deletions, so files deleted locally remain on the upstream side.rm -rfbeforeUPSTREAM_SKILL_PATHがskills/<name>・.agents/skills/<name>・.claude/skills/<name>is verified with a case statement to be one of the following, and any other value causes an abort. In addition, immediately before rm -rf, re-verify the real path (symlink boundary, check under the clone root, TOCTOU countermeasure via cd -P + relative rm). The deletion target must always be confined to under the temporary directory for clone (${WORKDIR}/upstream/), and no other files are touched at all.Step 5 must always be executed via${CONTRIBUTE_SKILL_DIR}/scripts/skills-contribute.sh(a path resolved separately from this skill's own placement. It is different fromLOCAL_SKILL_DIR, which is the path of the contribution target), and do not omit verification by typing the fragment commands individually - the copy source is applied only if it matches HEAD: The pre-review only shows committed diffs, whereas
cp -Rcopies the actual contents of the working tree, so uncommitted, untracked, and ignored files can be mixed into the upstream PR without review. The script${LOCAL_SKILL_DIR}undergit status --porcelain=v1 --untracked-files=all --ignoredand aborts if the output is non-empty.--untracked-files=allis omitted, untracked files are hidden by the user settingstatus.showUntrackedFiles=no, and--ignoredis omitted,.envetc. are copied. A non-zero exit (such as outside a git repository) is also not treated as clean.git update-index --assume-unchanged/--skip-worktreeChanges to files withgit statusare also not detected by - When a branch with the same name already exists: second-level slugs normally do not collide, but if they do, confirm with the user
Execution in a sandbox environment
This skill requires GitHub operations over the network (gh repo clone・git pushand PR creation). The relevant commands are executed with the sandbox disabled on a per-command basis. It cannot be executed in an environment where network blocking cannot be lifted.
Verification
After creating the PR, confirm completion with the following.
# PR が作成されたことを確認
gh pr view --repo "${REPO_SLUG}" --web
# または URL を直接確認(Step 9 で出力済み)
- A PR URL is returned
- The PR title and diff are as intended
sync-skills-lockThe execution guidance is output
Relationship with existing skills
- The security check in Step 4, Conventional Commits in Step 7, and the PR body in Step 8 are
create-pr/SKILL.mdFollows the style of - After merging,
sync-skills-lockでskills-lock.jsonのcomputedHashupdate