v5.4.0 アップグレードガイド

youtube-channels-automation v5.3.0 → v5.4.0 へダウンストリーム（チャンネルリポジトリ）を追従させるための手順。スキル名 rename（破壊的）、image_generator.py 削除に伴う import 経路変更、/streaming スキル + Terraform プロジェクト追加（オプトイン）、yt-discover-competitors CLI 追加（追加のみ）の 4 項目を扱う。

所要時間の目安: 5〜20 分（直 import 利用や 24/7 ライブ配信運用の有無による）

影響範囲のサマリー

#	変更項目	破壊的か	全チャンネル影響か
1	スキル名 rename（8 件）	はい	はい
2	`image_generator.py` 削除 → `image_provider/` モジュール	はい	直 import 利用時のみ
3	`/streaming` スキル + `infra/terraform/streaming/` 追加	いいえ	24/7 ライブ配信運用時のみ
4	`yt-discover-competitors` CLI + `discover-competitors` スキル追加	いいえ	追加のみ（破壊なし）

共通: automation を v5.4.0 に pin-bump

チャンネルリポジトリの pyproject.toml で automation のバージョンを v5.4.0 に上げる:

# 例（git+https インストールの場合）
dependencies = [
    "youtube-channels-automation @ git+https://github.com/daiki-beppu/youtube-automation@v5.4.0",
]

uv sync を走らせて新バージョンを取得:

uv sync --extra dev

1. スキル名 rename（破壊的）

やること

uv run yt-skills sync で新スキル群を .claude/skills/ 配下へ配布する
.claude/skills/ 配下の旧スキルディレクトリを削除する（手動 rm -rf）
CLAUDE.md / docs/ / shell alias / カスタムスクリプト中の旧スキル名（/analyze 等）を新名に置換する
Claude Code を再起動してスキル一覧が更新されたことを確認する

rename 早見表

旧	新
`analyze`	`analytics`
`collect`	`analytics`
`report`	`analytics`
`status`	`channel-status`
`description`	`video-description`
`upload`	`video-upload`
`ideate`	`collection-ideate`
`persona`	`audience-persona`

詳細手順

新スキルを配布:

uv run yt-skills sync

yt-skills sync --force はチャンネル側のスキル local 編集（.claude/skills/<skill>/SKILL.md への手書き加筆）を上書きで消す危険があるため、カスタマイズしていないことが確実な場合のみ使う。

旧スキルディレクトリを削除（rename 後はファイル名衝突しないため両方残ってしまう）:

rm -rf .claude/skills/{analyze,collect,report,status,description,upload,ideate,persona}

CLAUDE.md / docs/ / scripts/ / .claude/ 配下に旧スキル名の参照が残っていないか grep で点検し、新名に置換:

rg '/(analyze|collect|report|status|description|upload|ideate|persona)\b' \
   CLAUDE.md docs/ scripts/ .claude/

ヒットした各箇所を新スキル名に書き換える（例: /analyze → /analytics --analyze）。

#204 マージ後の差分

yt-skills sync --prune は本リリース時点では未実装（issue #204 で追加予定）。実装後は手動 rm -rf を打たずに以下のコマンド一発で旧スキル削除まで完結する想定:

# (#204 マージ後)
uv run yt-skills sync --prune

issue #204 がマージされたらこのガイドの該当ステップを更新する。

2. `image_generator.py` 削除 → `image_provider/` モジュール

やること

自リポジトリで youtube_automation.utils.image_generator を直接 import している箇所の有無を確認する
該当箇所があれば image_provider/ の新 API へ書き換える
OpenAI を画像プロバイダーに採用したい場合のみ、skill-config に image_generation: セクションを追加し OPENAI_API_KEY を 1Password に登録する

CLI 経由（yt-generate-image / yt-generate-thumbnail）でしか使っていない場合は 影響なし。

影響判定

# 自リポで image_generator を直 import している箇所を点検
rg 'from youtube_automation\.utils\.image_generator' .
rg 'youtube_automation\.utils\.image_generator' .

ヒットがゼロなら次セクションまでスキップしてよい。

旧 → 新 import

# 旧（v5.3.0 以前）
from youtube_automation.utils.image_generator import generate_image

# 新（v5.4.0）
from youtube_automation.utils.image_provider import get_provider, ImageGenerationRequest

image_provider パッケージの公開 API は以下:

get_provider(cfg: ImageGenerationConfig) -> ImageProvider
load_image_generation_config() / parse_image_generation_config(skill_cfg)
ImageGenerationRequest / ImageGenerationResult / ImageProvider
RETRY_MAX / RETRY_BACKOFF

呼び出しパターンは src/youtube_automation/commands/media/generate_image.py および src/youtube_automation/scripts/generate_thumbnail.py を参照。

`gemini_image:` 旧 namespace から `image_generation:` への移行（任意）

skill-config 上の旧 namespace gemini_image: は 後方互換のためロード継続 するが、DeprecationWarning を発行する。警告を抑止したい場合は新 namespace に書き換える。

# 旧（gemini_image: namespace）
gemini_image:
  model: gemini-3.1-flash-image-preview
  image_size: "2K"
  # ...

# 新（image_generation: namespace）
image_generation:
  provider: gemini
  gemini:
    model: gemini-3.1-flash-image-preview
    image_size: "2K"
    # ...

ロード優先順位は image_generation: > gemini_image: > 既定値。両 namespace が同時に存在する場合は新 namespace のみが採用される。

OpenAI を採用する場合

config/skills/thumbnail.yaml（チャンネル側 override）に image_generation: セクションを追加する:

image_generation:
  provider: openai
  openai:
    model: gpt-image-2
    quality: high          # low | medium | high
    aspect_ratio: "16:9"   # "16:9" または "9:16" のみ許容
    thinking: off          # off | low | medium | high（現 openai-python SDK は無視するため off 推奨。off 以外は warning が発火）
    batch: 1

aspect_ratio は "16:9" または "9:16" のみ。それ以外を指定すると ConfigError で起動失敗する（OpenAIConfig.__post_init__ の Fail Fast チェック）。

OPENAI_API_KEY は youtube_automation.utils.secrets 経由で解決される。解決順序は:

os.environ['OPENAI_API_KEY']
op read 'op://Personal/OpenAI_API_Key/credential'（1Password CLI）
どちらも失敗すれば ConfigError

1Password を使う場合は op item create で同 vault に OpenAI_API_Key アイテムを作成し credential フィールドに API key を保管する。

v5.4.0 では OAuth スコープ追加はないため auth/token.json の再生成は不要。

3. `/streaming` スキル + Terraform プロジェクト（オプトイン）

24/7 ライブ配信を行うチャンネルのみ対象。配信を行わないチャンネルは本セクションをスキップしてよい。

やること（24/7 ライブ配信運用チャンネルのみ）

uv run yt-skills sync で /streaming スキルを取得する
infra/terraform/streaming/ を upstream リポからチャンネルリポへコピー、または submodule で参照する
Vultr API key / YouTube Stream key / Discord webhook URL を 1Password に登録する
terraform.tfvars を作成し terraform init && terraform apply で配信を起動する

詳細手順

詳細仕様（前提・初回構築・動画差し替え・トラブルシュート）は upstream リポの infra/terraform/streaming/README.md に集約されている。本ガイドからは入口のみ示す。

# 1. /streaming スキルを取得
uv run yt-skills sync

# 2. infra/terraform/streaming/ をチャンネルリポにコピー、または submodule で参照
#    - コピー: cp -r <upstream>/infra/terraform/streaming infra/terraform/
#    - submodule: git submodule add <upstream>.git infra/streaming-shared

# 3. 1Password に以下のシークレットを登録:
#    - op://Personal/Vultr/api_key
#    - op://Personal/YouTube/stream_key
#    - op://Personal/YouTube_Stream_Discord_Webhook/url

# 4. terraform.tfvars を作成（video_path / allowed_ssh_cidr を埋める）
cd infra/terraform/streaming
cp terraform.tfvars.example terraform.tfvars
# → terraform.tfvars を編集

# 5. apply（詳細手順は README.md を参照）
terraform init
terraform plan
terraform apply

terraform.tfvars に Vultr API key / Stream key / webhook URL を直接書かない。TF_VAR_* 環境変数経由で 1Password から動的に渡す（README.md 参照）。

4. `yt-discover-competitors` CLI + `discover-competitors` スキル（追加のみ）

やること

uv sync で upstream を取得済みなら追加作業なし
uv run yt-skills sync で discover-competitors スキルを取得

uv sync
uv run yt-skills sync

pyproject.toml の youtube-channels-automation を v5.4.0 に pin、uv sync 完了
.claude/skills/ 配下に旧 8 スキル（analyze 等）が残っていない
.claude/skills/ 配下に新 8 スキル（analytics 等）が存在する
CLAUDE.md / docs/ / scripts/ / .claude/ から旧スキル名の参照が消えている（rg でゼロヒット）
youtube_automation.utils.image_generator を直 import しているコードがない（該当する場合のみ書き換え完了）
OpenAI provider を採用する場合: image_generation: セクション追加 + OPENAI_API_KEY を 1Password / 環境変数で解決可能
24/7 ライブ配信を行う場合: /streaming スキル取得 + infra/terraform/streaming/ 配置 + secrets 登録 + terraform apply 完了
コミット + push

v5.4.0 アップグレードガイド

影響範囲のサマリー

共通: automation を v5.4.0 に pin-bump

1. スキル名 rename（破壊的）

やること

rename 早見表

詳細手順

#204 マージ後の差分

2. `image_generator.py` 削除 → `image_provider/` モジュール

やること

影響判定

旧 → 新 import

`gemini_image:` 旧 namespace から `image_generation:` への移行（任意）

OpenAI を採用する場合

3. `/streaming` スキル + Terraform プロジェクト（オプトイン）

やること（24/7 ライブ配信運用チャンネルのみ）

詳細手順

4. `yt-discover-competitors` CLI + `discover-competitors` スキル（追加のみ）

やること

背景

トラブルシューティング

`yt-skills sync` 後も `/analyze` が見える

`ImportError: cannot import name 'generate_image' from 'youtube_automation.utils.image_generator'`

`DeprecationWarning: skill-config の \`gemini_image:` namespace は非推奨です`

`ConfigError: OpenAI image_generation.openai.aspect_ratio=... は未対応`

`ConfigError: OPENAI_API_KEY を取得できませんでした` が出る

Terraform の `Permission denied (publickey)`

チェックリスト