Communityライティング&編集github.com

tzwkb/repo-maintainer

エージェントスキル — GitHubリポジトリのクリーンアップ、統合、メンテナンス。

repo-maintainer とは?

このスキルは、断片化したGitHubプロフィールを整理・保守可能なプロフェッショナルなリポジトリ群に変革するための体系的なワークフローを提供します。6つのフェーズ(診断、基礎ファイルの標準化、古いリポジトリの処理、関連リポジトリのマージ、リネーム、コードレベルのリファクタリング)に分かれており、破壊的操作の前には必ずユーザーの確認を求めます。また、大規模なローカルリファクタリングをリモートにプッシュする際に必須の秘密情報スキャンや、Git履歴を破壊せずにコードを置き換える高度なGit操作(オーファンブランチ、ステージングされたリネーム戦略など)もカバーしています。Windows環境でのエンコーディング問題への対処法やGitHub APIの具体的な呼び出しパターンも提供しており、Claude Code、Cursor、CodexなどのAIエージェントが直接実行可能な実践的なスキルです。

対応~Claude Code~Codex CLI~Cursor
npx skills add tzwkb/repo-maintainer

Installed? Explore more ライティング&編集 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

リポジトリメンテナー

断片化したGitHubプロフィールを、クリーンで保守可能、プロフェッショナルなリポジトリ群に変革するための体系的なワークフロー。

概要

クリーンアップを6つのフェーズで実行します。該当しないフェーズはスキップしてください。破壊的操作(削除、リネーム、マージ)の前には必ずユーザーの確認を得てください。

基本原則(譲歩不可)

すべてのリポジトリ(新規・旧式、アクティブ・アーカイブ済みを問わず)に、以下の4つの基本ドキュメントが必須です。 4つすべてが確認できるまで、クリーンアップは完了したと見なさないでください。

ドキュメントルール理由
LICENSE公開リポジトリには必ずLICENSEを付与。デフォルトはMIT。ユーザーが別の指定をした場合はそれに従う。ライセンスがない場合、コードはデフォルトで「All rights reserved」となり、誰も法的に使用できません。
README.md最低限、プロジェクト名、1文の説明、該当する場合は使用/インストール手順が含まれていること。すべての訪問者が最初に目にするもの。READMEが空または欠落していると、放棄されたプロジェクトと思われます。
.gitignore主要言語(Python/PHP/Nodeなど)に適合していること。ビルド成果物、キャッシュ、環境ファイル、IDE設定を絶対にコミットしない。秘密情報の偶発的な漏洩を防ぎ、差分を読みやすくします。
GitHub Descriptiondescription フィールドは空にしてはいけません。1文で、平易な英語(またはリポジトリの言語に合わせる)。検索結果、プロフィールのピン留め、ソーシャルカードに表示されます。

リポジトリが4つのうちいずれかを欠いている場合、マージ、リネーム、リファクタリングよりも修正を優先してください。

フェーズ1: スキャンと診断

GitHub APIで完全なリポジトリリストを取得:

curl -sH "Authorization: Bearer TOKEN" \
  "https://api.github.com/user/repos?per_page=100&affiliation=owner"

各リポジトリについて以下を確認:

  • LICENSE、.gitignore、README.md の欠落
  • 空の description フィールド
  • 命名の不整合(大文字小文字の混在、過度に長い名前)
  • 明らかな重複やシリーズ(例: project、project-v2、project-mineru)
  • outdated、deprecated、old、test を含む名前

フェーズ2: 基礎ファイルの標準化

すべてのアクティブなリポジトリについて、最小限のファイルセットが存在することを確認:

ファイルルール
LICENSEデフォルトはMIT。ユーザーが別の指定をした場合はそれに従う。
.gitignore主要言語(Python/PHP/Node)に合わせる。
README.md存在すること。プレースホルダーのみの場合は書き換える。
GitHub DescriptionAPI経由で1文のサマリーを設定。

GitHub Contents API(PUT /repos/{owner}/{repo}/contents/{path})で一括更新。

重要: PowerShellのヒアドキュメントはMarkdownのトリプルバッククォートコードブロックを破損します。 READMEの一括生成にはPythonスクリプトを使用し、 ` → ``` のエスケープ失敗を回避してください。

フェーズ3: 古いリポジトリの処理

決定木:

条件アクション
名前に outdated / deprecated / old を含むアーカイブまたは削除
新しいリポジトリに置き換えられたアーカイブ + READMEに後継リンクを追記
公開リポジトリの履歴に漏洩した秘密情報(APIキー)が含まれる削除(アーカイブでは履歴が残る)
プライベートリポジトリにキー、パスワード、プライベート設定、個人データが含まれるユーザーは漏洩ルールを無視してよい。ユーザーが明示的にサニタイズを依頼しない限り、許容されるプライベートな状態として扱う。
参考として有用だがメンテナンスされていないアーカイブ

アーカイブされたリポジトリは読み取り専用です。アーカイブされたリポジトリを変更(リネーム、README更新)するには、まずアーカイブを解除し(PATCH {"archived": false})、変更を行い、再アーカイブします。

フェーズ4: 関連リポジトリのマージ

2つ以上のリポジトリが同一システムの派生版(異なるバックエンド、エンジン、アダプター)である場合:

オプションA — モノレポ(推奨) 新しいクリーンなリポジトリを作成(履歴なし)。各派生版を engines/{name}/ サブディレクトリに配置。

project-suite/
├── main.py              # デフォルトエンジン
├── engines/
│   ├── babeldoc/
│   └── mineru/
└── README.md

各エンジンのエントリポイントと設定を保持。ルートのREADMEに切り替え方法を説明。

オプションB — Git Submodule リポジトリを独立させたまま、親リポジトリにサブモジュールとして追加。履歴の保存がシンプルさより重要な場合に使用。

オプションC — 独立維持+リンク マージしない。READMEに相互リンクを追加。派生版が大きく分岐している場合に使用。

履歴に秘密情報が含まれる場合: 常に新しいクリーンなリポジトリを作成し、現在のスナップショットをコピー(zipダウンロード+再コミット経由)。履歴の漏洩が残るため、git merge や git submodule は使用しないでください。

フェーズ5: リポジトリのリネーム

APIパッチ: PATCH /repos/{owner}/{repo} に {"name": "new-name"}。

ガイドライン:

  • すべて小文字、ハイフンのみ
  • 最大3〜4単語
  • 冗長な単語を削除(based-on、design-and-development)
  • アーカイブ済みリポジトリには、まだ付いていない場合は outdated サフィックスを追加

GitHubは一定期間、古いURLを自動的にリダイレクトしますが、ブックマークやスクリプトは機能しなくなる可能性があります。スターやフォークのあるリポジトリをリネームする前に、ユーザーに確認してください。

フェーズ6: コードレベルのリファクタリング

リモート構造がクリーンになったら、リポジトリ内のコードをリファクタリング:

  1. 統一された用語 — ハードコードされたブランド名を汎用的な用語に置き換える(GPTProcessor → LLMProcessor)。ただし、実際のAPIモデルID(gpt-4、gpt-5)は維持。
  2. ファイルのリネーム — GitHub Contents APIにリネーム機能はなし。新しい内容で新しいファイルを作成し、古いファイルを削除。
  3. ディレクトリ再編成 — マルチフレーバープロジェクトには engines/、variants/、または core/ + adapters/ パターンを使用。

大規模なローカルリファクタリングをリモートにプッシュ

ユーザーがコードをローカルにダウンロードし、大幅な変更(ファイルリネーム、変数リネーム、構造的な書き換え)を行い、リモートリポジトリにプッシュバックする必要がある場合。

プッシュ前の秘密情報スキャン(必須)

プッシュ前は必ず秘密情報の漏洩をスキャンし、何か発見されたら即座に報告し、プッシュを続行してはいけません。

プライベートリポジトリの例外: 対象リポジトリがプライベートであることが確認できた場合、キー、パスワード、プライベート設定、個人情報、その他の機密情報の漏洩ルールを無視してもかまいません。スキャンは注意喚起として行いますが、ヒットしてもプッシュをブロックせず、リポジトリの削除・再作成を要求せず、環境変数への置き換えも要求しません。ただし、ユーザーが明示的にクリーンアップを依頼した場合や、リポジトリを公開する予定がある場合は例外です。

スキャンモード(両方実行すること — トークン用の正規表現だけでは平文パスワードを見逃します):

① 高エントロピートークン / APIキー:

grep -rn "sk-[A-Za-z0-9]\{20,\}\|ghp_[A-Za-z0-9]\{36\}\|ghu_\|github_pat_\|Bearer [A-Za-z0-9+/=]\{40,\}" \
  --include="*.py" --include="*.js" --include="*.ts" --include="*.yaml" \
  --include="*.env" --include="*.json" --include="*.bat" --include="*.sh" \
  --exclude-dir=".git" .

② 平文パスワード / 認証情報ヘルパー(トークン用正規表現では捕捉できない。実際に askpass.sh 内の echo "<sudoパスワード>" がinitコミットでGitHubに上がってしまった事例あり):

git ls-files -z | xargs -0 grep -nIE "password|passwd|パスワード|SUDO_ASKPASS|sshpass|^[[:space:]]*echo[[:space:]]+[\"'][^\"']{6,}[\"']" 2>/dev/null \
  | grep -vE "\.md:|getenv|getpass|placeholder|example"
# さらに、askpass.sh / *_secret* / .pgpass / .npmrc のようなファイルはファイル全体が認証情報である可能性があるため、手動で確認すること。

公開リポジトリの場合、いずれかのパターンにヒットしたら、以下の強制フローに従って処理してください。プライベートリポジトリの場合は、ユーザーに注意を促すだけで、ブロック条件とはなりません。スキャン対象は git ls-files(追跡ファイルセット)であることに注意。.gitignore で除外されたものは漏洩とはみなされませんが、すでにコミットされたファイルは、現在gitignoreされていても履歴に残り続けます。

報告形式:

[LEAK] scripts/eval.py:15 — sk-xxxx (ハードコードされたフォールバック)
[LEAK] ui/ui_backend.py:33 — sk-xxxx (ハードコードされたデフォルト)

漏洩発見後の強制フロー:

  1. どのファイルの何行目に問題があるか、すぐにユーザーに伝える
  2. 環境変数に置き換える(os.getenv("API_KEY")、デフォルト値なし)
  3. すでにリモートにプッシュされている場合: ユーザーに伝え、明確な確認を得た上でリポジトリを削除して再作成する(Git履歴はforce pushでは完全に消去できない)
  4. ユーザーに該当サービスのキーを無効化してもらう

プッシュ前チェックリスト

プッシュ前には必ず以下を実行:

git status

以下の状態がないことを確認:

  • Untracked files — 追跡されていない新しいファイル(よくある見落とし: docs/、scripts/、configテンプレート)
  • Changes not staged — 変更がaddされていない
  • Changes to be committed にアップロードすべきでないファイルが含まれている(キー、個人データ、一時スクリプト)

確認が取れるまで、直接プッシュしてはいけません。

決定木

状況推奨アクション
ローカルリポジトリに .git がない(ダウンロードしたzip / コピーしたファイル)下記シナリオAを参照
ローカルは git clone で履歴あり、リモートは 変更なし通常の git add → commit → push
ローカルは git clone で、リモートに新しいコミットがあるgit pull --rebase またはマージ、競合解決後、プッシュ
ローカルは git clone で、変更が大規模なリネーム+書き換え下記シナリオBを参照
リモートの履歴を保持しつつ、すべてのコードを置き換えたい下記シナリオCを参照

シナリオA: ローカルにGit履歴がない

ユーザーがzipをダウンロードして大幅に編集した後、同期したい場合に最も一般的。

オプションA1 — Force Push(個人/ソロプロジェクト向け)

# ローカルプロジェクトフォルダ内で
 git init
 git add .
 git commit -m "refactor: 大規模な書き換え"
 git remote add origin https://github.com/OWNER/REPO.git
 git branch -M main
 git push -u origin main --force

⚠️ リモートの履歴を破壊します。ユーザーがリモートの履歴を破棄してもよいと確認した場合のみ使用。

オプションA2 — リモート履歴を保持(価値のあるリポジトリに推奨)

 git clone https://github.com/OWNER/REPO.git temp-repo
 cp -r temp-repo/.git ./your-local-project/
 cd your-local-project
 git add .
 git commit -m "refactor: 大規模な書き換え"
 git push

これにより、過去のすべてのコミットが保持され、リファクタリングが1つの新しいコミットとして追加されます。

オプションA3 — 新しいクリーンなリポジトリ 書き換えが非常に根本的で、実質的に新しいプロジェクトになる場合:

  1. GitHub上に新しいリポジトリを作成(作成時に description を含めるか、作成直後にPATCHで設定)
  2. ローカルコードをそこにプッシュ
  3. 古いリポジトリをアーカイブし、READMEに後継リンクを追記

シナリオB: クローンしたリポジトリでの大規模なリネーム+書き換え

重要なルール: ファイルのリネームと内容の変更を同じコミットに混在させてはいけません。 Gitは「古いファイルの削除+新しいファイルの作成」として扱い、履歴のリンクが失われます。

段階的なコミット戦略:

# ステップ1: リネームのみ
 git mv old_module.py new_module.py
 git mv old_utils/ new_utils/
 git commit -m "refactor: モジュール名を変更"

# ステップ2: 変数/クラス名の変更
 git add .
 git commit -m "refactor: 変数とクラス名を変更"

# ステップ3: ロジックの変更
 git add .
 git commit -m "feat: コアロジックを更新"

ユーザーがすでにすべてをワーキングツリーで混在させてしまっている場合:

# 現在の変更をスタッシュし、段階的に再実行
 git stash push -m "混在したリファクタリング"

# リネームのみ復元(git mv または手動 mv + git add を使用)
 git mv old_file new_file
 git commit -m "refactor: ファイル名を変更"

# 内容の変更を復元
 git stash pop
 # 競合があれば解決し、コミット

シナリオC: 履歴を保持してすべてのコードを置き換える

新しいコードでスタートしたいが、スター/Issue/URLは維持したい場合に有効。

 git checkout --orphan fresh-start
 git rm -rf .
 # ここに新しいローカルコードをコピー
 git add .
 git commit -m "init: クリーンな書き換え"
 git branch -D main
 git branch -m main
 git push -u origin main --force

リネーム検出の確認

プッシュ後、Gitがリネームを正しく追跡しているか確認:

git log --follow -- new_file.py

履歴が壊れている(ファイルが真新しいものとして表示される)場合、リネームと内容の変更が一緒にコミットされています。

セキュリティとコンプライアンス

  • GitHubトークン: PATが必要な場合は、エージェントの記憶から探してください(ここに具体的なパス/アカウント/値を記述しないでください)。トークン値を、プッシュされる可能性のあるファイル(本スキル、README、設定ファイルを含む)に絶対に書き込まないでください — トークンを含む内容をプッシュすると、GitHubのsecret-scanningによって即座に無効化されます。
  • トークン管理: 一括操作後、ユーザーに https://github.com/settings/tokens でPATをすぐに失効させるよう指示してください。
  • プライベートリポジトリの例外: リポジトリがプライベートの場合、エージェントはキー漏洩、パスワード、プライベート設定、個人データ、その他の機密情報漏洩ルールを無視してもかまいません。ユーザーが依頼した場合やリポジトリが公開される可能性がある場合を除き、プッシュをブロックしたり、強制的にサニタイズしたり、削除を推奨したりしないでください。
  • 公開リポジトリの秘密情報履歴: 公開リポジトリがかつてAPIキーをコミットした場合、GitHubのバックアップシステムから履歴を完全に消去する唯一の方法はリポジトリを削除することです。force pushでサニタイズした履歴をプッシュしても、GitHubのバックアップシステムから削除されることは保証されません。
  • 秘密情報を含むアーカイブ済み公開リポジトリ: 削除が受け入れられない場合、少なくともリポジトリを公開から外す(プライベートにする)か、削除してクリーンなコードで空のリポジトリを再作成してください。

テクニカルリファレンス

エンコーディングの落とし穴(Windows)

PowerShellはデフォルトで標準出力にCP1252を使用するため、日本語やMarkdownコードブロックが破損します。常に再設定:

import sys
sys.stdout.reconfigure(encoding='utf-8')

PowerShellの Invoke-RestMethod をバッククォートやトリプルバッククォートを含むJSONボディとともに使用する場合は、JSONシリアライゼーションで ``` が ` に化けるのを避けるため、コンテンツ生成にはPythonスクリプトを使用してください。

GitHub APIパターン

リポジトリ作成(description を決して省略しない):

api_call("POST", "/user/repos", {
    "name": "repo-name",
    "private": True,
    "description": "1文のサマリー。"
})

ファイルの作成/更新:

import base64, json, urllib.request

payload = {
    "message": "コミットメッセージ",
    "content": base64.b64encode(content.encode('utf-8')).decode(),
    "sha": existing_sha  # 更新時は必須
}
req = urllib.request.Request(
    f"https://api.github.com/repos/{owner}/{repo}/contents/{path}",
    method="PUT",
    data=json.dumps(payload).encode(),
    headers={"Authorization": f"Bearer {token}", ...}
)

アーカイブ/アーカイブ解除:

api_call("PATCH", f"/repos/{owner}/{repo}", {"archived": True})

リポジトリのリネーム:

api_call("PATCH", f"/repos/{owner}/{repo}", {"name": "new-name"})

リポジトリの削除:

api_call("DELETE", f"/repos/{owner}/{repo}")

クローンせずに一括ダウンロード

不安定なネットワークで遅い git clone を避けるため、リポジトリのスナップショットをzipでダウンロード:

curl -sL "https://github.com/{owner}/{repo}/archive/refs/heads/main.zip" -o {repo}.zip

バンドルリソース

  • scripts/repo_analyzer.py — ユーザーのGitHubリポジトリをスキャンし、クリーンアップの推奨事項を生成
  • scripts/bulk_file_updater.py — GitHub API経由でLICENSE、.gitignore、READMEを一括作成/更新

関連スキル