この記事は playpark Blog からの転載です。
この記事で分かること
- スキルをプロジェクト間で使い回せない根本原因
- 3層コンフィグマージという設計の意図
- グローバル設定とプロジェクト設定をどう使い分けるか
背景: こういう課題があった
Claude Code Skillsは、繰り返し作業をAIワークフローとして定義する仕組みです。GA4分析、SNS投稿文の生成、記事公開フロー——それぞれをSkillとして書いておけば、どのプロジェクトでも呼び出せる。
はずでした。
実際には、スクリプトの中にプロジェクト固有値がベタ書きされています：
PROPERTY_ID="123456789" # このプロジェクトのGA4 ID
SITE="sc-domain:example.com" # このプロジェクトのGSC URL
2つ目のプロジェクトでも同じスキルを使うには、値を書き換えてコピペするしかない。そうすると同じスキルが2つに分裂し、片方だけバグ修正される状況が生まれます。
「自動化ツールを手動で移植する」という矛盾が発生していました。
選択肢の検討
プロジェクト間で設定を使い分ける方法はいくつかあります：
| アプローチ | 概要 | 問題点 |
|---|---|---|
| コピペして値を書き換え | スキルごとにプロジェクト用コピーを作成 | スキルが分裂、バグ修正が全スキルに波及しない |
| 環境変数で渡す |
.env ファイルにすべての設定を書く |
.env が肥大化、「どれがどのスキル用か」が不明 |
| 設定ファイルで外部化 | スクリプト外のJSONから設定を読む | 導入コストはあるが、スキル本体は共通のまま |
3つ目を体系化したのが skill-config.json による3層コンフィグマージです。
なぜこのアプローチを選んだか
根本的な問いは「何が変わって、何が変わらないか」の切り分けです。
変わらないもの（スキル本体）:
- スクリプトのロジック
- Claudeへの指示書
- エラーハンドリング
変わるもの（プロジェクト固有値）:
- GA4プロパティID
- ドメイン名
- 出力先ディレクトリ
「変わるもの」だけを外に出せば、スキル本体は一度書くだけで済みます。
3層の設計
外に出した設定を、どこに置くかにも意図があります：
スキル内蔵デフォルト ← グローバル設定 ← プロジェクト設定
（最低優先） （ユーザー共通） （最優先）
| 層 | パス | 置くもの |
|---|---|---|
| グローバル | ~/.config/skills/config.json |
タイムゾーン、言語、SNSデフォルト |
| プロジェクト | <project>/skill-config.json |
GA4 ID、ドメイン名、出力先 |
| デフォルト | スクリプト内の初期値 | フォールバック値 |
グローバル設定は「どのプロジェクトでも同じ値」のみを置きます。タイムゾーンは Asia/Tokyo 、投稿言語は ja 、SNS投稿先はデフォルトでXとLinkedIn。これらをプロジェクトごとに書き直す理由がない。
プロジェクト設定は「このプロジェクトだけの値」のみ。GA4プロパティIDは当然プロジェクトごとに異なります。
実装例
source "$SKILLS_DIR/_lib/common.sh"
config=$(load_skill_config "ga-analyzer")
# グローバル + プロジェクトのマージ済み設定が取れる
property_id=$(echo "$config" | jq -r '.property_id')
output_dir=$(echo "$config" | jq -r '.output_dir')
内部では jq の * 演算子でdeep mergeを実装しています：
echo "$global_cfg" | jq --argjson proj "$project_cfg" '. * $proj'
deep mergeを選んだのは、ネストしたオブジェクトの一部だけを上書きするためです。シャローマージだとネストしたオブジェクト全体が上書きされ、グローバル設定の大部分が消えてしまいます。
まとめ: どういう場面で使うべきか
この設計が効くのは「同じスキルを複数のプロジェクトで使い回したい」場面です。
スキルが1〜2個、プロジェクトも1つであれば、ベタ書きで十分です。複数プロジェクトにわたり、かつスキルが増えるにつれて設定管理のコストが上がってきた段階で導入を検討するのが現実的です。
逆に、この設計を入れておくと「新しいスキルを書く心理的ハードルが下がる」という二次効果があります。どのプロジェクトでも動くと分かっていれば、1つのスキルを書く投資の回収先が増えるからです。
さらに深掘りしたい方へ
この記事では3層コンフィグマージの設計意図を解説しました。
Skillsを「どのプロジェクトでも動く」ポータブル資産にする設計 ではさらに：
-
_lib/共有ライブラリによる重複コードゼロ化の実装詳細 - 外部スキル（skills.sh等）のsymlink統合と
.gitignore自動管理 - 旧形式設定ファイルを一斉移行せずに動かし続けるレガシーフォールバックの仕組み
を扱っています。
playpark について
playpark LLC - 業務自動化・AI活用・Web開発
