Agent Skills › K9i-0/ccpocket › shorebird-patch

shorebird-patch

GitHub

用于为移动应用创建并分发 Shorebird OTA 热修复补丁至 staging 环境。自动执行版本确认、平台补丁生成及资产差异检查，验证后提示用户手动执行 stable 升级。

.claude/skills/shorebird-patch/SKILL.md K9i-0/ccpocket

Trigger Scenarios

需要创建或发布 Shorebird 热更新补丁将代码变更以非侵入方式分发给测试用户

Install

npx skills add K9i-0/ccpocket --skill shorebird-patch -g -y

More Options

Non-standard path

npx skills add https://github.com/K9i-0/ccpocket/tree/main/.claude/skills/shorebird-patch -g -y

Use without installing

npx skills use K9i-0/ccpocket@shorebird-patch

指定 Agent (Claude Code)

npx skills add K9i-0/ccpocket --skill shorebird-patch -a claude-code -g -y

安装 repo 全部 skill

npx skills add K9i-0/ccpocket --all -g -y

预览 repo 内 skill

npx skills add K9i-0/ccpocket --list

SKILL.md

Frontmatter

{
    "name": "shorebird-patch",
    "description": "Shorebird OTA パッチの作成・staging 配布（stable 昇格はユーザー実施）",
    "allowed-tools": "Bash(bash:*), Bash(shorebird:*), Bash(dart:*), Bash(xcrun:*), Bash(grep:*), Read"
}

Shorebird パッチ配布

Shorebird OTA パッチを staging に作成する。stable への昇格はユーザーが検証後に手動で実施する。

新バージョンのリリースは /release-mobile スキルを使用する。アセット差分でパッチが適用されない場合も、/release-mobile でリリース後に再パッチする。

フロー概要

patch (staging) → デバッグ画面で検証 → ユーザーが promote (stable) → 全ユーザーに配信

パッチ手順

1. バージョン確認

grep '^version:' apps/mobile/pubspec.yaml

version: X.Y.Z+N の値を記録する（= <version>）。

2. パッチ作成 (staging)

指定済みのプラットフォームを優先し、未指定なら iOS と Android の両方を staging に作成する。対象とバージョンを報告して進め、追加の承認は求めない。対象リリースが存在しない場合は、そのプラットフォームの未完了理由を報告する。

# iOS
bash .claude/skills/shorebird-patch/patch.sh ios <version>

# Android
bash .claude/skills/shorebird-patch/patch.sh android <version>

# 両方の場合は順番に実行

スクリプトが以下を一括で行う:

shorebird patch で staging にパッチ作成
--allow-asset-diffs によりアセット変更の確認プロンプトを自動スキップ

完了後の出力から パッチ番号 を記録する（= <patch-number>）。

3. アセット差分の検証（重要）

パッチ出力に以下の警告が含まれていないか確認する:

[WARN] Your app contains asset changes, which will not be included in the patch.

この警告が出た場合、パッチは publish されるが実機に適用されない可能性が高い。

対処法

アセット差分が検出された場合、ユーザーに以下を報告する:

警告内容: どのファイルにアセット差分があるか（例: MaterialIcons-Regular.otf）
影響: パッチは作成されるが、デバイスでダウンロード後に適用されない
推奨対応: /release-mobile で新リリースを作成してから、クリーンな状態でパッチを再作成する

4. 検証（staging）

パッチが staging に配信されたら、以下の方法で検証する:

ローカル: shorebird preview --track=staging --release-version=<version>
実機（TestFlight等）: アプリのデバッグ画面（ロゴ5連打）→ Update Track を Staging に変更 → アプリ再起動

5. Promote (staging → stable)

このスキルでは stable への昇格は実行しない。検証が問題なければ、ユーザーが以下を手動実行する:

bash .claude/skills/shorebird-patch/promote.sh <version> <patch-number>

エージェントは promote を自動実行せず、上記コマンドをそのまま案内する。

6. 完了報告

以下を報告する:

パッチ番号
対象プラットフォーム
リリースバージョン
トラック: staging に配信済み
stable 昇格は未実施で、ユーザー実行待ちであること
アセット差分: あり/なし（ありの場合は警告を明記）
ユーザーがそのまま実行できる promote コマンド

npm scripts

npm run shorebird:patch:android -- <release-version>
npm run shorebird:patch:ios -- <release-version>
npm run shorebird:promote -- <release-version> <patch-number>

トラブルシュート

アセット差分でパッチが適用されない: --allow-asset-diffs でパッチ作成は成功するが、アセット変更（フォント、画像等）を含むパッチは実機で適用に失敗する。/release-mobile で新リリースが必要
署名エラー（exportArchive）: IPA生成時のエラーはShorebirdパッチ自体には影響しない。パッチが Published Patch N! と表示されていれば成功
インタラクティブプロンプト: shorebird コマンドを直接実行する場合は --release-version フラグ必須（省略するとインタラクティブプロンプトで非TTY環境がエラーになる）
パッチが反映されない場合の確認: 設定画面のバージョン表示で (patch N) が出ているか確認。出ていなければShorebirdリリースビルドでない可能性がある
staging パッチの確認方法: デバッグ画面（ロゴ5連打）→ Update Track を Staging に変更 → アプリ再起動