🔄 自動生成スキルを全プロジェクトに週次配布する

月10万の大学生だったころは「自動化」という言葉が遠かった。掛け持ちで月60万になり、会社都合で解雇されてゼロに戻り、半年かけてClaude Codeの自律環境を組み直して今は月商120万。その過程でわかったのは、稼ぐかどうかより先に「環境が自分で賢くなり続けるかどうか」が分岐点だということです。

---

なぜこの仕組みが効くのか

Claude Codeの ~/.claude/skills/auto/ はいわば個人の「手癖ライブラリ」です。作業中に発見した回避策・完了条件・検証コマンドをAIが自動でスキルファイルに書き出し、次の依頼で即座に参照できる──そういう仕組みになっています。

ところが現実は少し違います。

スキルは .claude/skills/auto/ に溜まり続けます。でも新しくgitリポジトリを切ったプロジェクト、数週間ぶりに開いた副業案件、別の言語で書いたツール群──これらにはそのスキルが最初から存在しない。人間が手でコピーするか、毎回「あのスキルを参照して」と指示を入れない限り、折角積み上げた手癖が別プロジェクトでは完全に死んでいます。

問題の構造はこうです。

• スキルは .claude/skills/auto/ という一か所に蓄積される（グローバル）
• 実際に参照されるのは「そのプロジェクトに .agents/ または .claude/skills/ があるとき」（ローカル）
• 新規プロジェクトを作るたびにその橋渡しは起きない（ゼロスタート）

これは「環境を育てる」ではなく「毎回育て直す」です。月商が一定ラインを超えると案件の掛け持ち数が増え、新規リポジトリを週に2〜3本切ることもある。そのたびにスキルの欠落に気づき、手動コピーして、確認して──という作業は静かに時間を食います。ツール呼び出し1回分の時間ではなく、「あのスキルが今ここにあれば3分で終わったのに」という機会損失です。

この問題を解決するのが週次の自動配布スクリプトです。毎週日曜の早朝、全gitリポジトリを走査してスキルを流し込む。人間が何もしなくても、月曜に開いたプロジェクトには最新のスキルが揃っている。

作業量を増やすのではなく、環境の品質を底上げする。 Claude Code自律環境を組む上で、この設計思想が一番効いています。

一点、重要な前提があります。ここで言う「スキル」とは、自前で積み上げた ~/.claude/skills/auto/ 配下のファイル群のことです。バンドルスキルや ~/.claude/skills/ecc/ には一切触れません。配布対象はあくまで自分の手癖ライブラリだけです。

---

全体の流れ

仕組み全体を俯瞰します。

[launchd]
com.shun.autoskills-sync
日曜 06:10 起動
        |
        v
[autoskills-sync.sh]
        |
        +-- ① オンライン確認
        |   curl -sf -m 8 https://registry.npmjs.org/
        |   オフライン → exit 0（何もせず正常終了）
        |
        +-- ② プロジェクト探索
        |   find ~ ~/dev -maxdepth 2
        |     -name .git  →  親ディレクトリをリスト
        |     -name package.json / pyproject.toml /
        |           requirements.txt / go.mod /
        |           Cargo.toml / pubspec.yaml /
        |           skills-lock.json
        |   sort -u で重複除去
        |
        +-- ③ 除外フィルタ
        |   oss-trial/* / *-public / node_modules/*
        |   Documents/ Library/ Applications/ go/
        |   .claude/ config-snapshots/ claude-obsidian/
        |   digital-products
        |
        +-- ④ 各プロジェクトへ配布
        |   npx -y autoskills --yes
        |   出力から「N skills installed」をパース
        |
        +-- ⑤ gitignore 追記（本番のみ）
        |   .agents/ / .claude/skills/ / skills-lock.json
        |
        +-- ⑥ ログ記録
            ~/.claude/logs/com.shun.autoskills-sync.log

launchd 設定：plistで「日曜 06:10」に固定

macOSのジョブスケジューラlaunchdは、~/Library/LaunchAgents/ に置いたplistを読み込んで自動実行します。com.shun.autoskills-sync.plist の中身はこうなっています。

<key>StartCalendarInterval</key>
<array>
  <dict>
    <key>Hour</key>
    <integer>6</integer>
    <key>Minute</key>
    <integer>10</integer>
    <key>Weekday</key>
    <integer>0</integer>
  </dict>
</array>

Weekday が 0 は日曜日です。毎週日曜の6時10分に起動します。RunAtLoad が false なので、plistをロードした瞬間には走りません。次の日曜まで待機します。

PATHの設定も入っています。

<key>EnvironmentVariables</key>
<dict>
  <key>PATH</key>
  <string>~/.nvm/versions/node/v24.13.0/bin:
          /opt/homebrew/bin:/opt/homebrew/sbin:
          /usr/local/bin:/usr/bin:/bin:...</string>
</dict>

launchdはシェルを経由しないため、通常の .zshrc が読まれません。nvmで管理しているNode.jsのパスを明示的にPATHへ書いておかないと、npx コマンドが見つからずに失敗します。/bin/zsh -lc で起動していますが、それでもlaunchdの環境では .zshrc は読まれないため、このPATH注入は必須です。

StandardOutPath と StandardErrorPath は両方とも ~/.claude/logs/com.shun.autoskills-sync.log に向いています。スクリプト内の log() 関数も同じファイルに追記するため、ログは1ファイルに集約されます。

①オンライン確認：8秒タイムアウトで安全に抜ける

if ! curl -sf -m 8 https://registry.npmjs.org/ >/dev/null 2>&1; then
  log "offline — skip"; exit 0
fi

起動タイミングがスリープ明けや機内モードと重なることがあります。そのときに npx を呼んでも失敗するだけなので、最初にnpmjsへのHTTP疎通を確認します。-m 8 で8秒以内に応答がなければオフライン扱いとし、exit 0 で正常終了します。エラーコードを返さない理由は、launchdがエラー終了をリトライのトリガーにすることがあるためです。

②プロジェクト探索：6種のマニフェストで言語を横断

find "$HOME_DIR" "$HOME_DIR/dev" -maxdepth 2 -name .git -type d 2>/dev/null \
  | sed 's|/\.git$||'

find "$HOME_DIR" "$HOME_DIR/dev" -maxdepth 2 \
  \( -name package.json -o -name pyproject.toml -o -name requirements.txt \
     -o -name go.mod -o -name Cargo.toml -o -name pubspec.yaml \
     -o -name skills-lock.json \) \
  -not -path '*/node_modules/*' 2>/dev/null | sed -E 's|/[^/]+$||'

探索は ~ と ~/dev の -maxdepth 2、つまり2階層までです。それ以上深いネストのディレクトリは対象外。この制限はパフォーマンスと意図的なスコープの両方に理由があります。

.git ディレクトリを探してその親を取る経路と、マニフェストファイルを探して親ディレクトリを取る経路の2系統をORで走らせ、sort -u で重複除去します。gitリポジトリでなくても package.json があれば対象になるし、gitリポジトリでも package.json がなければマニフェスト経路では拾われない──両方の経路で取りこぼしを防いでいます。

対応言語はJavaScript/TypeScript（package.json）、Python（pyproject.toml、requirements.txt）、Go（go.mod）、Rust（Cargo.toml）、Flutter/Dart（pubspec.yaml）、そしてAutoskillsが生成するlock（skills-lock.json）。実質的にほぼすべての個人開発スタックをカバーしています。

bash 3.2との互換性のため mapfile/readarray を使わず、while IFS= read -r line で配列に詰めています。macOSの /bin/bash はデフォルト3.2です。Homebrewでbash 5を入れていても、スクリプトの先頭行が #!/usr/bin/env bash であれば /bin/bash が呼ばれます。この落とし穴はコメントにも明記されています。

# NOTE: mapfile/readarray は macOS 標準 /bin/bash 3.2 に無いため使わない（3.2/5 両対応の while-read）

③除外フィルタ：なぜその4カテゴリを弾くのか

is_excluded() {
  local d="$1"
  [ "$d" = "$HOME_DIR" ] && return 0
  [ "$d" = "$HOME_DIR/dev" ] && return 0
  case "$d" in
    */oss-trial/*)  return 0 ;;   # 第三者fork
    *-public)       return 0 ;;   # 公開OSSミラー
    */node_modules/*) return 0 ;;
    "$HOME_DIR"/Documents/*|"$HOME_DIR"/Library/*|"$HOME_DIR"/Applications/*) return 0 ;;
    "$HOME_DIR"/Public/*|"$HOME_DIR"/go|"$HOME_DIR"/go/*) return 0 ;;
    */.claude/*|*config-snapshots*|*claude-obsidian*) return 0 ;;
    "$HOME_DIR"/digital-products|"$HOME_DIR"/digital-products/*) return 0 ;;
  esac
  return 1
}

除外ルールは4つのカテゴリに分けて読むとわかりやすいです。

ルートディレクトリ自身の保護。 $HOME と $HOME/dev はそれ自体を除外します。~/.claude/ や ~/.agents/ といった設定領域を上書きするリスクがあるためです。探索の起点であるこの2ディレクトリは、中身を対象にしても親自身は対象にしません。

第三者コードの保護。 */oss-trial/* は他人のOSSリポジトリをフォークして試している場所です。そこに自分のスキルを書き込むのは、レポジトリのオーナーの意図と関係ない変更が混入することを意味します。公開OSSミラーを指す *-public も同様です。これらのプロジェクトに対してautoskillsを走らせてしまうと、意図しない .gitignore の変更や skills-lock.json の生成が起き、公開リポジトリを汚染するリスクがあります。

macOSシステム領域の保護。 Documents/、Library/、Applications/、Public/、go/ はコードプロジェクトではありません。これらに package.json が偶然存在した場合でも除外します。Library/ にはAutoskillsとは無関係のアプリデータが大量にあり、誤って走らせると意図不明なファイルが生成されます。

Claude Code自身の設定領域の保護。 .claude/、config-snapshots、claude-obsidian はClaude Codeの設定ファイルや会話ログ、Obsidianのvaultです。これらはgit管理されていますが、スキル配布の対象ではありません。特に ~/.claude/ 自体が探索で引っかかる可能性があるため、明示的に除外しています。

コンテンツ系ディレクトリの保護。 digital-products はプロンプト集などのコンテンツ販売用ディレクトリで、コードスタックを持ちません。スキルを入れる意味がないため除外しています。コメントに「スタック無」と明記されているのは、将来誰かがこの設定を読んだときに除外理由がわかるようにするためです。

④配布：npxで毎回最新を取りに行く

out="$(cd "$d" && npx -y autoskills ${DRY:---yes} 2>&1)"
n="$(echo "$out" | grep -oE '([0-9]+) skills installed' | grep -oE '^[0-9]+' | head -1)"
[ -z "$n" ] && n="$(echo "$out" | grep -oE 'Skills to install \([0-9]+\)' | grep -oE '[0-9]+' | head -1)"
[ -z "$n" ] && n=0

npx -y autoskills --yes をプロジェクトディレクトリで実行します。-y はnpxの確認プロンプトを省略、--yes はautoskillsのインタラクションを省略します。2>&1 で標準エラーも取り込み、$out 変数に全出力を格納してからパースします。

出力フォーマットが「N skills installed」と「Skills to install (N)」の2パターンあることに対応するため、grepを2段階で書いています。どちらにもマッチしなければ n=0 として扱い、0のプロジェクトはログに「0 (skip)」と記録してそのまま次へ進みます。

${DRY:---yes} はbashのパラメータ展開です。DRY 変数が非空（--dry-run フラグあり）のときは --dry-run を渡し、空のときは --yes を渡します。これにより手動実行でも本番実行でも同じスクリプトを使い回せます。

⑤gitignore追記：スキルをリポジトリから隔離する

if [ -z "$DRY" ] && (cd "$d" && git rev-parse --git-dir >/dev/null 2>&1); then
  for pat in ".agents/" ".claude/skills/" "skills-lock.json"; do
    grep -qxF "$pat" "$d/.gitignore" 2>/dev/null || echo "$pat" >> "$d/.gitignore"
  done
fi

スキルが1件以上インストールされたgitリポジトリにだけ実行されます。.agents/、.claude/skills/、skills-lock.json の3パターンを .gitignore に追記しますが、grep -qxF で事前に存在確認し、すでにある行は重複追記しません。

この処理が重要な理由は、チームリポジトリや公開リポジトリへ誤ってスキルをコミットするリスクを防ぐためです。スキルファイルは個人の環境依存であり、他の開発者の環境では意味をなさないか、むしろ混乱を招きます。

--dry-run のときは DRY が非空なので [ -z "$DRY" ] が偽となり、gitignore追記はスキップされます。ドライランは読み取りのみ、という原則を徹底しています。

⑥ログ：1ファイルに全情報

実行のたびに ~/.claude/logs/com.shun.autoskills-sync.log へタイムスタンプ付きで追記します。

[2026-07-13 06:10:03] ==== autoskills-sync start ====
[2026-07-13 06:10:04]   lead-finder: 12 skills
[2026-07-13 06:10:06]   affiliate-fc2: 8 skills
[2026-07-13 06:10:08]   note-autolike: 0 (skip)
[2026-07-13 06:10:09]   oss-trial: (excluded)
[2026-07-13 06:10:10] ==== done: 2 projects / 20 skills, 1 excluded ====

完了行の done: N projects / M skills, K excluded のフォーマットで、配布されたプロジェクト数・スキル総数・除外数が一目でわかります。週に1回しか走らないため、ログが肥大化するペースも緩やかです。

実装の詳細

set -uo pipefail ──3フラグを揃える理由

スクリプト冒頭の1行です。

set -uo pipefail

-u（nounset）は未定義変数を展開しようとしたときにエラーで停止します。タイポしたまま rm -rf "$UNDEFINED_DIR/" のようなコードが走ることを防ぎます。ただし後述しますが、空配列に対しては -u が意図外の動作をするため、別途ガードが必要になりました。

-o pipefail はパイプラインの途中コマンドが失敗したとき、パイプ全体の終了コードを「最初に失敗したコマンドのコード」にします。grep -oE '...' | head -1 のような多段パイプで、最初のgrepが空マッチでも head -1 が 0 を返して成功扱いになる罠を防ぎます。

-e（errexit）はあえて付けていません。is_excluded 関数が return 0（除外=真）を返す動作は、シェルから見ると「コマンドが失敗した」に映ります。-e があるとこの関数を呼んだ時点でスクリプト全体が終了します。条件分岐を含む関数に -e は鬼門です。エラーハンドリングは明示的な || { log "..."; exit 1; } で書くほうが誤爆がない。

サブシェルcdパターン ──作業ディレクトリを汚染しない

out="$(cd "$d" && npx -y autoskills ${DRY:---yes} 2>&1)"

cd "$d" && npx ... をコマンド置換 $() で囲んでいます。cd の効果をサブシェルに閉じ込めるためです。 $() 内は独立したシェル環境なので、内部での cd は親シェルのカレントディレクトリに影響しません。これがないと、ループの2回目以降で npx が前のプロジェクトディレクトリで実行され続ける可能性があります。

gitignore の確認部分も同じ考え方です。

if [ -z "$DRY" ] && (cd "$d" && git rev-parse --git-dir >/dev/null 2>&1); then

こちらは $() でなく () ですが目的は同じ。「$d がgitリポかどうかを親シェルのcdなしに確認する」ワンライナーとして機能します。条件判定のために cd したいが、その cd をループに引き継がせたくないとき、() はシンプルで確実な手段です。

bash 3.2互換性 ──mapfile禁止の背景

最初は mapfile でコレクションを作ろうとしました。

# 書きたかったが書けなかった
mapfile -t CANDIDATES < <(find ...)

macOSのデフォルト /bin/bash はバージョン3.2です。mapfile（別名 readarray）はbash 4.0以降の機能なので、/bin/bash で実行するとそのまま command not found です。スクリプト先頭が #!/usr/bin/env bash であっても、launchdのPATH設定によっては /bin/bash（3.2）が呼ばれます。コメントにも明記されています。

# NOTE: mapfile/readarray は macOS 標準 /bin/bash 3.2 に無いため使わない（3.2/5 両対応の while-read）

解決策は while IFS= read -r ループです。

CANDIDATES=()
while IFS= read -r line; do
  [ -n "$line" ] && CANDIDATES+=("$line")
done < <(
  { find "$HOME_DIR" "$HOME_DIR/dev" -maxdepth 2 -name .git -type d 2>/dev/null | sed 's|/\.git$||'
    find "$HOME_DIR" "$HOME_DIR/dev" -maxdepth 2 \
      \( -name package.json -o -name pyproject.toml -o -name requirements.txt \
         -o -name go.mod -o -name Cargo.toml -o -name pubspec.yaml \
         -o -name skills-lock.json \) \
      -not -path '*/node_modules/*' 2>/dev/null | sed -E 's|/[^/]+$||'
  } | sort -u
)

IFS= でフィールド分割を無効化し、-r でバックスラッシュエスケープを無視することで、スペースや括弧を含むパスでも1行ずつ正確に読み込めます。[ -n "$line" ] で空行を弾いているのは、sort -u の出力末尾に空行が混じることがある（環境依存）からです。

空配列ガード ──set -u の罠

# bash 3.2 + set -u では空配列の "${arr[@]}" が unbound で落ちるためガード
if [ "${#CANDIDATES[@]}" -eq 0 ]; then
  log "==== no candidates found; nothing to sync ===="
  exit 0
fi

set -u が有効なとき、bash 3.2では空配列 CANDIDATES=() に対して "${CANDIDATES[@]}" を展開するとunbound variable エラーになります。bash 5.x では空配列を展開しても問題ありませんが、3.2では「存在するが空の配列」を「未定義変数」として扱うケースがある。

${#CANDIDATES[@]} は配列の要素数を返します。これは空配列でも 0 を返し、set -u があってもエラーになりません。このガードを入れることで、候補ゼロのときもログに理由を残して正常終了できます。

2段階grepの必要性

n="$(echo "$out" | grep -oE '([0-9]+) skills installed' | grep -oE '^[0-9]+' | head -1)"
[ -z "$n" ] && n="$(echo "$out" | grep -oE 'Skills to install \(([0-9]+)\)' | grep -oE '[0-9]+' | head -1)"
[ -z "$n" ] && n=0

autoskillsの出力フォーマットはバージョン間で変わりました。以前は 12 skills installed という形式でしたが、あるバージョンから Skills to install (12) という形式も混在するようになりました。片方にしか対応していないと、もう一方のバージョンでは常に n=0 になり、実際にスキルが入っていても全プロジェクトが「skip」扱いになります。

head -1 を付けているのは、grep -oE が全マッチを複数行で出力するとき、後続の [ "$n" -gt 0 ] の数値比較に改行込みの値が渡されてエラーになることへの保護です。

---

私が詰まった話

詰まり① launchdがnpxを見つけられない

最初にplistを書いてロードしたとき、スクリプトは起動しているのにログに何も出ませんでした。launchctl list com.shun.autoskills-sync でステータスを確認すると終了コード 127。コマンドが見つからないエラーです。

症状: ジョブが起動した記録はあるのにログファイルが空。autoskillsの出力も何もない。

原因: launchdは通常のログインシェルと独立した環境で動くため、.zshrc に書いたnvmのパス設定が一切読まれません。/usr/bin/npx は存在しないし、.nvm 以下のnpxはlaunchdの素のPATHに含まれていない。スクリプト自体は起動できても、その中で呼ぶ npx が見つからない状態でした。

直し方: plistの EnvironmentVariables にnvmのパスを含めたフルPATHを明示します。

<key>EnvironmentVariables</key>
<dict>
  <key>PATH</key>
  <string>~/.nvm/versions/node/v24.13.0/bin:/opt/homebrew/bin:/opt/homebrew/sbin:
          /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:~/.local/bin</string>
</dict>

nvmのバージョンを v24.13.0 と固定しているのは意図的な判断です。.nvm/alias/default から動的に解決しようとすると、シェル展開が使えないplistでの記述が複雑になります。固定することで設定が確実に動く。代わりに、nvmでNodeバージョンを切り替えたときはplistも更新する運用が必要です。

ProgramArguments が /bin/zsh -lc スクリプトパス になっているのもこの経緯からです。最初は /bin/bash スクリプトパス でしたが、-l（ログインシェル）を付けると /etc/zprofile 等が読まれ、環境が本番に近くなります。それでもnvmのパスは .zshrc にしか書かれていないため、EnvironmentVariables による明示注入が最終的に必要でした。

詰まり② --dry-runなのにgitignoreが書き換わった

初期バージョンで --dry-run フラグを付けて実行したのに、複数のプロジェクトの .gitignore が書き換わりました。

症状: ドライランのはずが、git diff を走らせると .gitignore に3行追記されている。

原因: 初期実装では gitignore 追記ロジックに DRY チェックが入っていなかった。npxには --dry-run を渡せていましたが、gitignore の追記部分はフラグを見ておらず、スキルのインストール件数（n > 0）だけを条件にしていたため、ドライランでも書き換えが走っていました。

# 問題のあった初期バージョン
out="$(cd "$d" && npx -y autoskills --dry-run 2>&1)"
n=...  # パース
if [ "$n" -gt 0 ]; then
  # DRYチェックなしでgitignoreを書き換えていた
  for pat in ".agents/" ".claude/skills/" "skills-lock.json"; do
    grep -qxF "$pat" "$d/.gitignore" 2>/dev/null || echo "$pat" >> "$d/.gitignore"
  done
fi

直し方: gitignore 追記ブロックの手前に [ -z "$DRY" ] を追加します。

if [ -z "$DRY" ] && (cd "$d" && git rev-parse --git-dir >/dev/null 2>&1); then
  for pat in ".agents/" ".claude/skills/" "skills-lock.json"; do
    grep -qxF "$pat" "$d/.gitignore" 2>/dev/null || echo "$pat" >> "$d/.gitignore"
  done
fi

$DRY が空（＝本番実行）のときだけ追記する。この修正後は --dry-run が「副作用ゼロの確認モード」として正しく機能するようになりました。

教訓は「フラグの意味を実装レベルで統一する」です。--dry-run を受け取ったなら、副作用のある操作はすべて DRY チェックで囲む。「npxには渡したから大丈夫」という部分的な適用では、思わぬ書き換えが残ります。

詰まり③ 空配列でset -uがスクリプトを無言で落とした

set -uo pipefail を追加した直後の実行で、スクリプトが起動ログの1行も出さずに終了するようになりました。

症状: launchdのステータスコードが 1。ログファイルは完全に空。起動した形跡すらない。

原因の特定: bash -x autoskills-sync.sh でトレース実行すると、こんなエラーが出ました。

+ for d in "${CANDIDATES[@]}"
autoskills-sync.sh: line 63: CANDIDATES[@]: unbound variable

set -u が有効なとき、bash 3.2では空配列 CANDIDATES=() に対して "${CANDIDATES[@]}" を展開するとunbound variable エラーになります。log() 関数の呼び出しより前にbashが死ぬため、ログに何も残りません。 これがログが空だった理由です。

直し方: for ループの手前に配列サイズチェックを入れます。

if [ "${#CANDIDATES[@]}" -eq 0 ]; then
  log "==== no candidates found; nothing to sync ===="
  exit 0
fi

${#CANDIDATES[@]} は空配列でも 0 を返し、set -u でもエラーになりません。このガードを追加した後は、空配列でもログに理由が残って exit 0 するようになりました。

デバッグで効いた手順: launchdのジョブは週1回しか動かないため、「おかしい」と気づくまでに1週間かかります。問題の切り分けはターミナルから bash -x autoskills-sync.sh --dry-run を手動実行するのが最速です。トレース出力には変数の展開過程が全部出るため、どの行で死んだかが一目でわかります。週次ジョブのデバッグサイクルを短縮するには、「手動でも同じスクリプトを引数だけ変えて走らせられる」設計が必須だとこの件で確信しました。

詰まり④ Library/配下の謎プロジェクトが配布対象になった

ある週の実行ログに見覚えのないエントリが記録されていました。

[2026-XX-XX 06:10:33]   Caches: 3 skills

~/Library/Caches の中に npmパッケージのキャッシュが存在し、そこに package.json があったのです。マニフェスト探索の find が ~/Library/ を2階層まで見るため、キャッシュの package.json を「プロジェクト」として拾っていました。当時の is_excluded にはまだ Library/* の除外ルールがありませんでした。

症状: 意図しないキャッシュディレクトリに autoskills が実行され、skills-lock.json が生成される。gitリポでないため gitignore への追記は起きなかったが、キャッシュにロックファイルが残った。

直し方: 除外ルールに Documents/*、Library/*、Applications/* を追加します。

"$HOME_DIR"/Documents/*|"$HOME_DIR"/Library/*|"$HOME_DIR"/Applications/*) return 0 ;;

現在のスクリプトにはこの行が含まれており、Library 配下はすべて除外されます。

この経験から設計方針が固まりました。「コードのプロジェクトがある場所を能動的に定義する」のではなく、「コードのプロジェクトでない場所を除外する」ことで安全側に倒す。macOSのホームディレクトリは思った以上に package.json や go.mod が散在しています。探索範囲を広げるほど誤爆が増えるため、探索は ~ と ~/dev の2階層に絞りつつ、除外ルールは手厚くするというバランスが今の形です。

---

4つの詰まりは全部「ローカルで手動実行しているときは出なかった問題」でした。launchdで週1回だけ動く仕組みは、何かおかしくても1週間気づかない。そのコストが高いから、--dry-run で先に確認してログで後追いできる構造にしています。月曜の朝に開いたプロジェクトに最新スキルが揃っているのは、この地道な失敗の積み重ねがあってこそです。

つまずきポイント

前章では「ローカル手動実行では出なかったlaunchd固有の問題」を4事例取り上げました。ここでは周辺でさらに踏んだ細かい罠を箇条書きで網羅します。

plist の ~ はチルダ展開されない

EnvironmentVariables の PATH に ~/.nvm/versions/node/v24.13.0/bin と書いても、launchdはチルダ展開を行いません。~ をそのまま文字列として解釈するため、/usr/bin/npx も ~/.nvm/... 配下のnpxも見つからない状態になります。解決策はホームディレクトリのフルパスを書くことのみです。実際のplistでもフルパスが記述されており、~ は一切使われていません。

RunAtLoad を true にすると plist ロード直後に本番実行が走る

launchctl load ~/Library/LaunchAgents/com.shun.autoskills-sync.plist を実行した瞬間にスクリプトが起動します。除外ルールの確認も --dry-run もまだしていない段階で全プロジェクトが走ることになります。初回は必ず RunAtLoad を false にしておき、launchctl start com.shun.autoskills-sync で手動トリガーして動作を確認してから次の日曜を待ちます。現在のplistは <false/> に固定されているのはこの理由からです。

Weekday=0 が日曜というlaunchd固有の数え方

macOSのlaunchd plistは 0=日曜、1=月曜、…、6=土曜 です。「週の始まりは月曜=1」という感覚で Weekday を 1 に設定すると、月曜ではなく火曜に動く設定になります。com.shun.autoskills-sync.plist の Weekday が 0 なのは「日曜早朝に走って月曜の作業開始前に配布を済ませる」という意図です。plistを書いた直後は launchctl start で即時実行し、ログに残るタイムスタンプで曜日のズレがないことを確認します。

launchctl load だけでは変更が反映されない

plistを書き換えた後 launchctl load だけ再実行しても、launchdは古い設定を保持し続けます。変更を反映するには launchctl unload ~/Library/LaunchAgents/com.shun.autoskills-sync.plist を先に実行し、その後 launchctl load を実行します。「設定を直したのに動きが変わらない」という状況はほぼ例外なくこれが原因です。

LastExitStatus=0 が「正常終了した」とは限らない

launchctl list com.shun.autoskills-sync の出力に "LastExitStatus" = 0; があっても、これは「前回の実行が正常終了した」だけでなく、「まだ一度も実行されていない（初期値が0）」の場合もあります。ログファイルにエントリが存在するかどうかで「本当に実行されたか」を確認します。ログが空のまま LastExitStatus=0 という状況は「初回ロード直後でまだ日曜が来ていない」であることが多いです。

npx の -y と autoskills の --yes は別の確認を省略する

npx -y はnpxが「このパッケージをダウンロードしますか？」と確認するプロンプトを省略します。autoskills --yes はautoskills自身のインタラクティブ確認を省略します。どちらか片方だけ付けても、もう一方で止まります。launchdの無人実行ではプロンプト待ちが永続するため、次の日曜まで止まり続けても誰も気づかない最悪のパターンになります。スクリプトの ${DRY:---yes} はDRYが空のとき --yes を渡すパラメータ展開ですが、初期実装では変数代入前に展開してしまい常に空文字列が渡っていたことがありました。

sort -u を省くと同一プロジェクトに2回実行される

.git 探索経路とマニフェストファイル探索経路は独立して走ります。.git があり package.json もあるプロジェクトは両経路から同じパスが出てきます。sort -u がなければループが同一ディレクトリで2回実行されます。2回目は「インストール済み」として0件になるだけで実害は小さいですが、通信・時間・ログエントリが余計に増えます。

grep -qxF の -F（固定文字列）と -x（行全体一致）の意図

gitignore追記の確認で -F を省くと .agents/ の先頭 . が正規表現ワイルドカードになります。xagents/ という行があっても「マッチあり」と判定され、本来の .agents/ パターンが追記されません。-x を省くと # .agents/ というコメント行にも部分マッチして「追記不要」と誤判定します。どちらが欠けても「実際には効いていないのに追記されたと思い込む」結果になります。

ProcessType が Adaptive（省略時）だと省エネモードでキャンセルされる

plist に ProcessType を書かないか Adaptive にすると、macOSの省エネ制御下でジョブが延期または中断されることがあります。スリープ明けに日曜06:10のトリガーが過ぎていた場合、Background ならそのウィンドウを維持しますが Adaptive では消える場合があります。週に1回しかないチャンスが省エネで飛ぶコストは無視できません。現在のplistには <key>ProcessType</key><string>Background</string> が明示されています。

実行権限とplistの起動方式の関係

plistの ProgramArguments を ["/bin/zsh", "-lc", "スクリプトパス"] の形にすると、zsh 経由で実行するためスクリプト自体の実行権限（+x）は不要になります。["/path/to/script.sh"] の形（直接実行）にすると +x が必須です。直接実行形式で +x を忘れると終了コード 126（Permission denied）でサイレントに失敗します。現在のplistが /bin/zsh -lc 形式なのは、ログインシェルとの互換性だけでなく権限問題の回避も兼ねています。

---

ベストプラクティス

実際に動かして得た運用の型を、再現性の高い順に並べます。

1. 変更したら即 --dry-run を先に走らせる

bash ~/.claude/scripts/autoskills-sync.sh --dry-run

除外ルールを追加したとき、探索パスを変えたとき、plistを書き換えたとき、どんな変更の後でもこの1行を先に打ちます。ドライランは副作用ゼロで何回でも実行できます。週次ジョブの最大の弱点は「問題に気づくまでに1週間かかる」ことで、この手順ひとつで予防的に潰せます。特にドライラン実行後のログ末尾に done: N projects / M skills の数字が出ているかを目視します。

2. stdout と stderr を同一ファイルへ集約する

plistの StandardOutPath と StandardErrorPath を同じパスに向け、スクリプト内の log() 関数も tee -a で同ファイルに追記します。2ファイルに分けると「エラーと通常出力がどの順番で出たか」を再現するのが困難になります。1ファイルの時系列ログで全経緯が追えます。com.shun.autoskills-sync.plist では両パスとも ~/.claude/logs/com.shun.autoskills-sync.log に向いています。

3. 除外ルールは「許可リスト」でなく「禁止リスト」で安全側に倒す

「コードプロジェクトだとわかる場所だけ許可する」設計より「コードプロジェクトでないと確実にわかる場所を禁止する」設計のほうが安全です。macOSのホームディレクトリは package.json や go.mod が意外な場所に散在します。探索範囲は ~ と ~/dev の maxdepth 2 に絞り、禁止リスト（is_excluded 関数）を手厚くするバランスが安定します。新しい領域を探索対象にしたくなったら、その前に必ず --dry-run でどのプロジェクトが追加されるかを確認します。

4. plist の EnvironmentVariables にはフルパスを書く

~ はplistでは展開されません。nvm管理のNode.jsを使う場合、バージョンを固定したフルパスを PATH に書きます。Node.jsバージョンを nvm use で変えたときはplistの該当箇所も同時に更新します。忘れると次の日曜に「npx: command not found」で全件スキップという静かな事故が起きます。バージョン固定は管理上の手間が増えますが、.nvm/alias/default から動的解決する複雑な記述より明示的なほうが信頼できます。

5. サブシェルcdで作業ディレクトリを汚染しない

out="$(cd "$d" && npx -y autoskills ${DRY:---yes} 2>&1)"

$() の中で cd することでディレクトリ移動をサブシェルに閉じ込めます。ループの次のイテレーションに cd の効果が引き継がれません。gitignore確認の (cd "$d" && git rev-parse ...) も同様です。「カレントディレクトリに依存するコマンドをループで回す」ときはこのパターンが最もシンプルで確実です。

6. mapfile を使わず while IFS= read -r で bash 3.2 互換を保つ

macOSのデフォルト /bin/bash はバージョン3.2です。mapfile（readarray）はbash 4.0以降の機能です。while IFS= read -r ループで代替し、コメントに「なぜmapfileを使わないか」を残しておきます。半年後の自分が「最適化」と称して mapfile に書き換えて動かなくなる事故を防ぎます。IFS= でフィールド分割を無効化し -r でバックスラッシュエスケープを無視することで、スペースや括弧を含むパスでも正確に読み込めます。

7. 空配列ガードを set -u の手前に入れる

if [ "${#CANDIDATES[@]}" -eq 0 ]; then
  log "==== no candidates found; nothing to sync ===="; exit 0
fi

set -u が有効なとき、bash 3.2では空配列に対して ${arr[@]} を展開するとunbound variableエラーになります。${#arr[@]} は空配列でも 0 を返し、set -u でもエラーになりません。このガードがないと候補ゼロのとき「ログが空のまま終了コード1」という状況が生まれます。エラーは無言で起きるため1週間気づかないことになります。

8. autoskills の出力フォーマット変化に2段階grepで対応する

n="$(echo "$out" | grep -oE '([0-9]+) skills installed' | grep -oE '^[0-9]+' | head -1)"
[ -z "$n" ] && n="$(echo "$out" | grep -oE 'Skills to install \(([0-9]+)\)' | grep -oE '[0-9]+' | head -1)"
[ -z "$n" ] && n=0

npmパッケージの出力フォーマットはバージョン間で変わります。1パターンだけに対応していると、バージョンアップ後に全件が「0件（skip）」として記録され、実際にはスキルが入っていることに気づかない状態が続きます。head -1 を付けているのは、複数行マッチが返ってきたとき後続の数値比較でエラーになることへの保護です。

9. gitignore 追記には -qxF を3文字セットで使う

grep -qxF "$pat" "$d/.gitignore" 2>/dev/null || echo "$pat" >> "$d/.gitignore"

-q（quiet・マッチの有無だけ返す）・-x（行全体一致）・-F（固定文字列）は3つ揃って機能します。-F がないと .agents/ の先頭 . が正規表現ワイルドカードになります。-x がないと # .agents/ というコメント行にも部分マッチします。どちらが欠けても「ない行を見つけたと誤判定してスキップ」または「別の行にマッチして重複追記」のいずれかが起きます。

10. ログの完了行に件数サマリーを含める

==== done: 2 projects / 20 skills, 1 excluded ====

週次実行のため、過去ログとの比較がしやすいフォーマットを固定します。「先週は20件、今週は0件」という変化をすぐに検知できます。「何かがおかしい」に気づく機会が週に1回しかないため、ログの情報密度は高くしておきます。tail -5 ~/.claude/logs/com.shun.autoskills-sync.log で直近の完了行だけ確認する習慣を作ると、週次確認が30秒で終わります。

11. RunAtLoad を false にして初回は launchctl start で確認する

launchctl load ~/Library/LaunchAgents/com.shun.autoskills-sync.plist
launchctl start com.shun.autoskills-sync
tail -20 ~/.claude/logs/com.shun.autoskills-sync.log

RunAtLoad=false のままplistをロードし、launchctl start で手動トリガーすることで「日曜まで待たずに動作確認」と「意図しない即時実行の防止」を両立します。初回確認でログに done: 行が出ていれば設定は正しく機能しています。

12. ProcessType を Background に明示する

<key>ProcessType</key>
<string>Background</string>

省略（Adaptive）にするとmacOSが「今は後回しにしてもよい」と判断した場合にジョブがスキップされる可能性があります。週に1回しかないチャンスが省エネで飛ぶコストは無視できません。Background の明示はjob schedulingにおける保険です。

13. plist を変更したら unload → load の順序を守る

launchctl unload ~/Library/LaunchAgents/com.shun.autoskills-sync.plist
launchctl load  ~/Library/LaunchAgents/com.shun.autoskills-sync.plist

load だけ再実行しても古い設定が残ります。「設定を直したのに動きが変わらない」はほぼ例外なくunloadを忘れていることが原因です。セットで1コマンド化しておくか、手順をコメントに残すかのどちらかで防ぎます。

14. Node.js バージョンを変えたら plist も更新する

nvmでNode.jsのバージョンを切り替えたとき、plistの EnvironmentVariables の PATH 内のバージョン番号も更新が必要です。これを忘れると古いバージョンのnpxが使われ続けます。nvm use を実行したタイミングでplistの更新を習慣化するか、使用バージョンをコメントに書いておいて定期確認します。自動化のための自動化が静かに古いまま動き続けるのは、誰でも踏む罠です。

15. set -e をあえて付けない設計意図を把握しておく

スクリプト冒頭に set -e がない理由は、is_excluded 関数が return 1（除外しない=false）を返したときにシェルが「コマンドが失敗した」と解釈するためです。set -e が有効だと if is_excluded "$d"; then の条件評価中に return 1 が出た時点でスクリプト全体が終了するケースがあります。条件分岐を含む関数を多用する場合、set -e より明示的な || { log "error: ..."; exit 1; } のほうが誤爆が少ないです。set -u と pipefail だけを残した現在の設定は、この判断の結果です。

---

まとめ

スキルが蓄積されても届かなければ意味がない──この単純な問題が、週次の自動配布という仕組みを生みました。

autoskills-sync.sh の88行は、オフライン確認・2経路の探索・5カテゴリの除外・npx実行・gitignore追記・件数ログという6ステップを一本に繋いだものです。plistはそれを毎週日曜06:10に自動起動します。手動で何もしなくても、月曜の朝に開いたプロジェクトには最新スキルが揃っている状態を作るための、最小限の仕掛けです。

本記事で取り上げたつまずきポイントとベストプラクティスの根底には共通する1つの設計思想があります。「週1回しか動かないジョブは、問題に気づくまでに1週間かかる」。だから --dry-run で先に確認し、ログに件数サマリーを残し、手動でも同じスクリプトが走らせられる設計にする。この3点が揃っていれば、launchdの周辺で起きる大半の事故は事前に防げます。

環境を育てるとは、スキルを蓄積することだけではありません。そのスキルが必要な場所に届く仕組みを作り、その仕組み自体を安全に運用する設計を育てることです。月商120万を支える環境は、こういう地味な週次ジョブの積み重ねで成り立っています。

---

仕組みの全体像・月120万の内訳・30日手順は有料noteにまとめています。

📕 Claude Code自律環境で、実際どう稼ぐか ― 仕組み・実例・始め方・サポート

---

Lily（@bokuwalily）― 個人開発者。Claude Code で自動化基盤を組みながら、iOSアプリやWebサービスを量産しています

• 制作物・記事は bokuwalily.com にまとめています🖥️
• AIで「寝てても回る仕組み」を作って月120万にした話は noteの有料記事 に💰
• OSS: github.com/bokuwalily 🐙
• 最新情報・お問い合わせは X @bokuwalily へ🌍

皆さんの ❤️ やシェアが励みになります！