octkp/base-readme

base README Updater

~/base リポジトリの README 群を、実際のディレクトリ構成から導出して更新・新規作成するスキル。

設定ファイルの追加・削除・移動のあとに走らせることで、README が実態とズレるのを防ぐ。冪等に作る（同じ状態で何度走らせても結果が同じ）。

対象ファイル

このスキルが触るのは以下の README のみ：

| パス | 内容 | |------|------| | README.md（リポジトリ直下） | リポジトリ全体の概要・セットアップ・使い方 | | dotfiles/README.md | 各ツール設定ディレクトリの一覧 | | home/README.md | home-manager 設定ファイルの一覧と編集方法 | | local/README.md | git追跡外のローカルファイル置き場の説明 | | scripts/README.md | セットアップスクリプトの説明 | | docs/README.md | ドキュメント類の説明 |

README 以外のファイルには一切書き込まない。

ワークフロー

1. リポジトリルートの解決

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
[ -z "$REPO_ROOT" ] && REPO_ROOT="${CLAUDE_PROJECT_DIR:-$HOME/base}"
if [ ! -f "$REPO_ROOT/flake.nix" ]; then
  echo "ERROR: base リポジトリが見つかりません（flake.nix が無い）。~/base 内で実行してください。" >&2
  exit 1
fi
cd "$REPO_ROOT"

2. 各ディレクトリの実態を走査

README を書く前に、必ず現在の中身を確認する。ハードコードした内容を流用せず、毎回スキャンして導出すること。

# 直下のファイル・ディレクトリ構成
for d in . dotfiles home local scripts docs; do
  echo "### $d"
  /bin/ls -1A "$REPO_ROOT/$d" 2>/dev/null
done

各ディレクトリでは以下も確認する：

• home/ … *.nix ファイルと programs/ 配下。default.nix の home.file シンボリックリンク定義も読むと「どの dotfiles がどこに配置されるか」が正確に書ける。
• dotfiles/ … サブディレクトリ名と、各々が何のツールの設定かを推定（不明なら中身を覗く）。
• scripts/ … 各スクリプトの先頭コメント／用途。
• local/ … .gitignore の /local/* 除外ルールと、現在置かれているもの。
• docs/ … サブディレクトリ構成と用途。

3. README を生成・更新

既存 README の体裁（後述「スタイル規約」）に合わせて、Read → Edit/Write で更新する。MISSING のものは新規作成、既存のものは実態に合わせて差分更新する。

4. 結果サマリと commit

更新したファイルを列挙して報告し、README だけを git add して commit & push する（base リポジトリはコミット・プッシュを確認なしで自動実行してよい運用）。

cd "$REPO_ROOT"
git add README.md dotfiles/README.md home/README.md local/README.md scripts/README.md docs/README.md
git commit -m "docs: README を現状のディレクトリ構成に合わせて更新" \
  -m "Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>"
git push

変更が無ければ commit はスキップする（冪等）。

スタイル規約

既存 README に合わせる。新規作成時も以下を踏襲：

• 言語は日本語。
• 見出しは # <dir>/（直下 README は # base）。直下に1行の用途説明。
• 構成は ## ファイル構成 の Markdown テーブル（| ファイル | 説明 |）で表す。
• そのディレクトリ特有の「○○したいとき」の操作例があれば ## セクションで添える（例: home/README.md の「パッケージを追加したいとき」）。
• コードブロックには言語指定（bash, nix 等）を付ける。
• リポジトリ直下の README.md は、## 概要 のツリー図・## ファイルの役割・## よく使うエイリアス などのテーブルを実態に同期させる。CLAUDE.md と矛盾しないこと。

各 README に必ず含める要素

• dotfiles/README.md: サブディレクトリ一覧テーブル（ディレクトリ名 → 何の設定か）。home-manager で ~/ 配下にリンクされるものはその旨を注記。
• home/README.md: *.nix ファイル一覧、パッケージ／エイリアス追加手順、hm-switch での反映。
• local/README.md: 「git追跡しないが Mac のバックアップには含める」用途、.gitignore の /local/*（README のみ追跡）ルール、現在の中身テーブル。
• scripts/README.md: 各スクリプトの説明と実行方法。
• docs/README.md: ドキュメントのサブディレクトリ構成と用途。
• 直下 README.md: ツリー図に主要ディレクトリ（local/ を含む）を反映。

注意

• README 以外（.nix、設定本体、local/ の中身など）は絶対に書き換えない。
• local/ 配下の実ファイルは gitignore 対象。local/README.md だけが追跡対象なのでそこだけ更新する。
• 機微情報（本番DBエンドポイント、トークン等）を README に転記しない。local/ の中身を列挙する際もパス名・用途にとどめる。