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 から旧バージョンのファイルを見つけます。

📖 まとめ


📝 練習問題

  1. 基礎問題(難易度⭐):作成した Skill にバージョン番号と CHANGELOG を追加してください。
  2. 応用問題(難易度⭐⭐):互換性のないアップグレードを設計し、マイグレーションガイドと互換レイヤーを含めてください。
  3. チャレンジ問題(難易度⭐⭐⭐):バージョンロック、自動チェック、アップグレード承認フローを含むチームバージョン同期メカニズムを設計してください。
Web-Tutorial.com

Web-Tutorial 技術チーム

複数の開発者によって共同維持されているプログラミングチュートリアルプラットフォーム。各チュートリアルは専門分野の開発者が執筆・レビューしています。正確で信頼性の高いコンテンツを目指しています — 問題を見つけた場合はお知らせください。

100%