Release Har Skill

Universal release automation skill. Works with any project.

Quick Reference

• “release” → /release-har
• “bump version” → /release-har patch
• “minor release” → /release-har minor
• “preview only” → /release-har --dry-run

References

Branch Policy

単独開発プロジェクトでは main への直接 push を許容する。

• CI が push: branches: [main] で全検証を実行するため、PR なしでも品質ゲートは機能する
• release.yml が v* タグ push 時に GitHub Release の存在を保証するセーフティネットとして動作する
• force push（--force / --force-with-lease）は禁止

共同開発者がいるプロジェクトでは、PR 経由のマージに切り替えること。

Execution Flow

Pre-flight: 事前チェック（必須）

リリース開始前に以下を確認する。失敗した場合はリリースを停止し修正を促す。

# 1. gh コマンドの存在確認
if ! command -v gh &>/dev/null; then
  echo "⚠️  gh コマンドが見つかりません。GitHub Release の作成はスキップします。"
  GH_AVAILABLE=false
else
  GH_AVAILABLE=true
fi

# 2. 未コミット変更の確認
if ! git diff --quiet || ! git diff --cached --quiet; then
  echo "❌ 未コミットの変更があります。コミットまたはスタッシュ後にリリースしてください。"
  git status --short
  exit 1
fi

# 3. バージョンファイル同期確認（VERSION と plugin.json が存在する場合）
if [ -f "VERSION" ] && [ -f ".claude-plugin/plugin.json" ]; then
  V_VERSION=$(cat VERSION | tr -d '[:space:]')
  V_PLUGIN=$(grep '"version"' .claude-plugin/plugin.json | sed 's/.*"version": "\([^"]*\)".*/\1/')
  if [ "$V_VERSION" != "$V_PLUGIN" ]; then
    echo "❌ バージョン不一致: VERSION=$V_VERSION, plugin.json=$V_PLUGIN"
    echo "   修正: ./scripts/sync-version.sh sync"
    exit 1
  fi
fi

Step 1: 変更分析

以下を並列取得する。

# 前タグを取得
PREV_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null \
  || git tag --sort=-v:refname | head -1 2>/dev/null \
  || echo "")

# 構造化コミットログ（フォーマット: {hash}|{subject}|{author}|{date}）
if [ -n "$PREV_TAG" ]; then
  LOG=$(git log --format="%h|%s|%an|%ad" --date=short "${PREV_TAG}..HEAD")
else
  LOG=$(git log --format="%h|%s|%an|%ad" --date=short --all | head -20)
fi

# OWNER/REPO 取得（gh 優先 → git remote フォールバック）
if command -v gh &>/dev/null; then
  REPO_FULL=$(gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null || echo "")
fi
if [ -z "${REPO_FULL:-}" ]; then
  REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
  REPO_FULL=$(echo "$REMOTE_URL" \
    | sed -E 's|https://github\.com/||; s|git@github\.com:||; s|\.git$||')
fi

Conventional Commits 分類

BREAKING CHANGE 検出: feat!: / fix!: 等の ! 付きタイプ、または本文に BREAKING CHANGE: を含むコミット。

Conventional Commits を使っていないプロジェクトでは、Claude がコミットメッセージを意味的に判断して分類する。

変更分析サマリ表示

📊 変更分析サマリ (vPREV → vNEW候補)
━━━━━━━━━━━━━━━━━━━━━━━━━
- feat     : N 件  → Added
- fix      : M 件  → Fixed
- other    : L 件  → Changed
- breaking : K 件  → Breaking Changes ⚠️
─────────────────────────────────
- contributors: X 名
- compare: https://github.com/{OWNER}/{REPO}/compare/{PREV_TAG}...HEAD
━━━━━━━━━━━━━━━━━━━━━━━━━

Step 2: SemVer 判定

Step 1 の分析結果に基づいてバージョンを提案する。

PREV_VERSION=${PREV_TAG#v}   # "v1.2.3" → "1.2.3"
MAJOR=$(echo "$PREV_VERSION" | cut -d. -f1)
MINOR=$(echo "$PREV_VERSION" | cut -d. -f2)
PATCH=$(echo "$PREV_VERSION" | cut -d. -f3)

if [ "${BREAKING_COUNT:-0}" -ge 1 ]; then
  SUGGESTED_VERSION="$((MAJOR+1)).0.0"   # major
elif [ "${FEAT_COUNT:-0}" -ge 1 ]; then
  SUGGESTED_VERSION="${MAJOR}.$((MINOR+1)).0"  # minor
else
  SUGGESTED_VERSION="${MAJOR}.${MINOR}.$((PATCH+1))"  # patch
fi

表示例: 📦 SemVer 判定: MINOR (1.2.3 → 1.3.0) 理由: feat: 3件, fix: 2件, breaking: 0件

0.x.y 初期開発段階: MAJOR=0 の場合は SemVer 2.0.0 §4 に従い、breaking change でも minor バンプ (0.x+1.0) または major (1.0.0) をユーザーに選択させる。

Step 3: diff 要約 & Release Notes 草稿生成

コミットメッセージだけでなく実際のコード差分を読み、Highlights と Before/After テーブルを生成する。

# 変更ファイルを確認（テスト・ロックファイルは低優先）
git diff --stat "${PREV_TAG}..HEAD"

# 重要ファイルの diff を読む（src/ 配下を優先）
git diff "${PREV_TAG}..HEAD" -- <重要ファイルパス> | head -100

Claude が生成するもの（最大3件）:

• Highlights: ユーザー視点での価値（1-3文）
• Before / After テーブル: 変更前後の状態

テンプレート詳細: references/release-notes-template.md

Step 4: dry-run プレビュー（デフォルト前段）

本実行前に必ずプレビューを表示する（--dry-run なし通常実行でも同様）。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 リリースプレビュー: v{PREV} → v{NEW}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 タグ: vX.Y.Z
📁 更新ファイル: CHANGELOG.md, VERSION, package.json（存在する場合）

📄 CHANGELOG エントリ（全文）:
{CHANGELOG エントリ}

🧹 Documentation Cleanup:
  CHANGELOG: {正規化対象 N 件}（日付フォーマット、セクション見出し等）
  README: {更新対象 M 件}（バージョン参照、機能一覧等）

📝 GitHub Release Notes（全文）:
{4セクション構造の Release Notes}

🔗 Compare URL: {COMPARE_URL}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
この内容で実行しますか？ (yes / no / 修正指示)

--dry-run オプション時: プレビュー後に終了（本実行なし）。

Step 5: CHANGELOG 更新（存在する場合）

CHANGELOG.md があれば更新する。フォーマット詳細: references/changelog-format.md

## [X.Y.Z] - YYYY-MM-DD

### 🎯 What's Changed for You

**{one-line バリュー要約}**

| Before | After |
|--------|-------|
| {旧状態} | {新状態} |

### Added
- **{Feature}**: {description}

### Fixed
- **{Fix}**: {description}

CHANGELOG_ja.md が存在する場合は同内容を日本語で更新する。

CHANGELOG が存在しない場合はスキップ。

Step 5.5: Documentation Cleanup（既存ドキュメント整備）

リリースのタイミングで、既存ドキュメントの品質も整える。新規エントリの追加だけでなく、過去の汚れも修正する。

CHANGELOG 既存エントリの正規化

過去エントリが Keep a Changelog 1.1.0 に準拠していない場合、正規化する。

CHANGELOG_ja.md が存在する場合、同等の整備を実施する。

README の更新

判断基準: 明らかに古い・壊れている箇所のみ修正する。意図的なスタイルの違いは尊重する。README が存在しない場合はスキップ。

Step 6: バージョンファイル更新

プロジェクトに応じてバージョンを更新する。

該当ファイルが存在しない場合はスキップ。

Node.js プロジェクト: npm version patch --no-git-tag-version も利用可。

Step 7: コミット & タグ

# 変更対象ファイルのみ明示的に追加（git add -A は使用しない）
git add CHANGELOG.md README.md VERSION package.json  # 実際に変更したファイルのみ

# コミット（変更がある場合のみ）
git commit -m "chore: release vX.Y.Z"

# タグ作成
git tag -a vX.Y.Z -m "Release vX.Y.Z"

Step 8: Push

git push origin $(git branch --show-current)
git push origin vX.Y.Z

Step 9: GitHub Release（オプション）

ユーザー確認後に GitHub Release を作成する。Release Notes は英語必須。

gh release create vX.Y.Z \
  --title "vX.Y.Z - {release title}" \
  --notes "$(cat <<'EOF'
## What's Changed

**{one-line バリュー要約}**

### Before / After

| Before | After |
|--------|-------|
| {旧状態} | {新状態} |

---

## Highlights

- **{Feature}**: {description}

## Notable Changes

### Added

- **{feature}**: {description}

### Fixed

- **{fix}**: {description}

## Full Changelog

**Full Changelog**: ${COMPARE_URL}

---

Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

フォーマットルール: .claude/rules/github-release.md テンプレート詳細: references/release-notes-template.md

必須事項:

• Release Notes は英語
• Before/After テーブルは省略不可
• Generated with [Claude Code](https://claude.com/claude-code) フッターは省略不可
• Breaking Changes がない場合はそのセクションを省略
• Highlights は最大3件

Step 10: X (Twitter) 告知文生成（--announce 指定時のみ）

/release-har --announce で実行した場合、GitHub Release 作成後に X 向け告知文を自動生成する。

生成ロジック

Step 3（diff 要約）で生成した Highlights のうち最も重要な1〜2点を1行ずつに圧縮し、280文字以内の告知文を作成する。

フォーマット

🚀 v{VERSION} released!

{Highlights から抽出した1行要約（日本語または英語、プロジェクトの言語に合わせる）}
{2行目（任意）}

{GitHub Release URL}

例:

🚀 v1.3.0 released!

Pre-flight checks + Claude diff summarization で配信品質が向上。
SemVer 自動判定と dry-run プレビューで事故を防止。

https://github.com/OWNER/REPO/releases/tag/v1.3.0

制約

生成後、そのままコピーできる形式でユーザーに提示する。投稿は Claude では行わない（手動コピー＆ペースト）。

Options

Related Skills

• x-release-harness – Harness plugin 専用リリース（ローカルのみ）
• verify – リリース前の検証