Skills: バージョン管理と更新
最終更新:2026-08-31
Skill は書いて終わりではない——進化するもの。バージョン管理で進化を追跡可能、ロールバック可能、調整可能にする。
1. セマンティックバージョニング
(1) バージョン番号のルール
TEXT
📖 参照専用
MAJOR.MINOR.PATCH
MAJOR:互換性のない変更(出力フォーマット変更、ツールバインディング変更)
MINOR:後方互換の追加(レビュー観点の追加、トリガーの追加)
PATCH:後方互換の修正(プロンプトの最適化、サンプルの更新)
(2) バージョン変更の例
| 変更 | バージョンアップ | 理由 |
|---|---|---|
| セキュリティレビュー観点を追加 | 1.0.0 → 1.1.0 | 後方互換の追加 |
| プロンプトの曖昧さを修正 | 1.1.0 → 1.1.1 | 後方互換の修正 |
| 出力フォーマットを JSON に変更 | 1.1.1 → 2.0.0 | 互換性のない変更 |
| Git トリガーを追加 | 2.0.0 → 2.1.0 | 後方互換の追加 |
2. 変更履歴
(1) CHANGELOG フォーマット
MARKDOWN
# Changelog
## [2.1.0] - 2026-08-20
### Added
- Git diff トリガーを追加
- Mermaid チャート出力オプションを追加
### Changed
- レビュープロンプトを最適化し、ハルシネーション出力を削減
### Fixed
- ネストされたコードブロックのパースエラーを修正
## [2.0.0] - 2026-08-01
### Breaking
- 出力フォーマットをプレーンテキストから Markdown 構造化に変更
- 変数名を `file` から `target_file` に変更
### Migration
- 変数参照の更新:`{{file}}` → `{{target_file}}`
- 出力パースは新フォーマットに対応が必要(マイグレーションガイドを参照)
(2) マイグレーションガイド
互換性のない変更には必ずマイグレーションガイドを添付:
MARKDOWN
## マイグレーションガイド:v1 → v2
### 変数の変更
- `{{file}}` → `{{target_file}}`
- `{{level}}` → `{{severity_level}}`
### 出力フォーマットの変更
- v1 プレーンテキスト → v2 Markdown 構造化
- 深刻度マーク:`[CRITICAL]` → `🔴`
### ツールバインディングの変更
- 新しい依存:Grep(コンテキスト検索用に追加)
3. 後方互換性戦略
(1) 互換性の原則
TEXT
📖 参照専用
互換性3原則
├── 出力フォーマット:新しいフィールドの追加が旧フィールドに影響しない
├── 変数システム:新変数にデフォルト値があり、旧変数は引き続き使用可能
└── トリガー:新しいトリガーの追加が既存のトリガーを破壊しない
(2) 廃止フロー
TEXT
📖 参照専用
廃止フロー(3バージョンにまたがる)
1. v1.1.0:廃止マーク、ただし引き続き使用可能、警告を出力
2. v1.2.0:デフォルトで無効、明示的な有効化が必要
3. v2.0.0:完全に削除
(3) 互換レイヤー
MARKDOWN
## 互換レイヤーの設計
新旧両方の変数名をサポート:
{{#if target_file}}
対象ファイル:{{target_file}}
{{#else if file}}
⚠️ 変数 `file` は廃止されました。`target_file` を使用してください
対象ファイル:{{file}}
{{/if}}
4. チーム同期更新
(1) 更新戦略
| 戦略 | 説明 | 適している |
|---|---|---|
| 自動更新 | PATCH バージョンは自動適用 | 小規模修正 |
| 通知更新 | MINOR バージョンはユーザーに通知 | 新機能 |
| 承認更新 | MAJOR バージョンは人工確認が必要 | 互換性のない変更 |
(2) 同期フロー
TEXT
📖 参照専用
チーム Skill 更新フロー
1. メンテナが新バージョン + CHANGELOG を公開
2. チームに通知(Slack/メール/PR コメント)
3. チームメンバーが git pull で更新を取得
4. MAJOR バージョンはマイグレーションガイドのレビューが必要
5. ローカルでテスト検証
6. 確認後、プロジェクトの適応変更をコミット
(3) バージョンロック
YAML
# プロジェクトで Skill バージョンを固定
skills:
code-review:
version: "^1.5.0"
deploy:
version: "2.0.0"
❓ よくある質問
Q 毎回の変更でバージョン番号を上げる必要がありますか?
A プロンプトの微調整(言い回しの最適化など)は不要です。出力フォーマット、変数、ツールバインディングに影響する変更には必要です。
Q チームメンバーが更新していない場合は?
A CI で Skill バージョンをチェックし、バージョンが古い場合はビルドを失敗させ、更新を促します。
Q 旧バージョンに戻すには?
A
git checkout v1.5.0 -- .claude/skills/code-review.md、または CHANGELOG から旧バージョンのファイルを見つけます。📖 まとめ
- セマンティックバージョニング:MAJOR は非互換、MINOR は追加、PATCH は修正
- 変更履歴:Added / Changed / Fixed / Breaking + マイグレーションガイド
- 後方互換性:追加が旧有に影響しない、廃止は3バージョンにまたがる、互換レイヤー
- チーム同期:PATCH は自動、MINOR は通知、MAJOR は承認
📝 練習問題
- 基礎問題(難易度⭐):作成した Skill にバージョン番号と CHANGELOG を追加してください。
- 応用問題(難易度⭐⭐):互換性のないアップグレードを設計し、マイグレーションガイドと互換レイヤーを含めてください。
- チャレンジ問題(難易度⭐⭐⭐):バージョンロック、自動チェック、アップグレード承認フローを含むチームバージョン同期メカニズムを設計してください。