octkp/ba2-skills-readme

BA2 Skills README Generator

skills/ 配下に置かれている各スキルの SKILL.md をスキャンして、人間がパッと見て「どんなスキルがあって、いつ使うのか」を把握できる skills/README.md を自動生成・更新するスキル。

このスキルは hooks からも、ユーザーの明示リクエストからも呼ばれることを想定している。冪等（同じ状態で何度呼んでも結果が同じ）に作る。

出力先

• 生成・更新するファイル: skills/README.md（このスキルが触る唯一のファイル）
• スキルディレクトリ自体には書き込まない。コミットもプッシュもしない（人間が PR 経由で行う）。

対象範囲

走査対象は skills/*/SKILL.md のみ：

• skills/<skill-name>/SKILL.md … Claude 用スキル本体（必須）
• skills/<skill-name>/.codex/SKILL.md … Codex 版（任意。存在チェックのみして「Codex 版あり」と一覧に注記する）

.codex/SKILL.md の中身は読まない。Claude 版（SKILL.md）の description をスキル一覧の説明として採用する。

ワークフロー

1. リポジトリ・対象パスの解決

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
[ -z "$REPO_ROOT" ] && REPO_ROOT="${BA2_WORKSPACE:-${CLAUDE_PROJECT_DIR:-}}"
if [ -z "$REPO_ROOT" ] || [ ! -d "$REPO_ROOT/skills" ]; then
  echo "ERROR: REPO_ROOT が解決できません。BA2_WORKSPACE 環境変数を設定するか、ba2-workspace リポ内で実行してください。" >&2
  exit 1
fi
SKILLS_DIR="$REPO_ROOT/skills"
README_PATH="$SKILLS_DIR/README.md"
cd "$REPO_ROOT"

• REPO_ROOT 解決の優先順位: ① git rev-parse --show-toplevel → ② 環境変数 BA2_WORKSPACE → ③ $CLAUDE_PROJECT_DIR（hook 経由で起動された場合は自動でセットされる）。どれも解決できなければエラーで止める。
• SKILLS_DIR が存在しなければ何もしないで終了する（対象なし）。

2. スキル一覧の収集

$SKILLS_DIR 配下の各サブディレクトリを走査する：

for dir in "$SKILLS_DIR"/*/; do
  [ -d "$dir" ] || continue
  name=$(basename "$dir")
  skill_md="$dir/SKILL.md"
  codex_md="$dir/.codex/SKILL.md"
  [ -f "$skill_md" ] || continue   # SKILL.md が無いディレクトリはスキップ
  # 後続でフロントマター抽出
done

• SKILL.md が存在しないディレクトリ（中途半端な状態）は黙ってスキップする。
• ディレクトリ名のアルファベット昇順で並べる（for のグロブ展開順 = 昇順なのでそのまま）。

3. SKILL.md からメタ情報を抽出

各 SKILL.md について以下を取得する：

| 項目 | 取得元 | 用途 | |---|---|---| | name | フロントマターの name: | 表のスキル名・アンカー | | description | フロントマターの description: | 表の「概要・トリガー」列、詳細セクション本文 | | 見出し（タイトル） | 本文最初の # 行 | 詳細セクションのタイトル | | Codex 版の有無 | .codex/SKILL.md の -f | 表の「Codex 版」列に ✓ |

description は複数行になっていることがあるので、YAML のマルチライン記法（> / 折り畳み）にも対応する必要があるが、現状の ba2 スキルはすべてシングルラインの長文で書かれている前提で OK。改行が入っていたら 1 行に詰めて取り出す（半角スペース1個で連結）。

Read ツールで各 SKILL.md を読み、Claude 側でパースするのが最も確実。bash で awk を使うなら：

# name の抽出
awk '/^---$/{f++;next} f==1 && /^name:/{sub(/^name:[[:space:]]*/,""); print; exit}' "$skill_md"
# description の抽出（複数行は連結）
awk '
  BEGIN{f=0; collecting=0; desc=""}
  /^---$/{f++; if(f==2) exit; next}
  f==1 {
    if (/^description:/) { sub(/^description:[[:space:]]*/,""); desc=$0; collecting=1; next }
    if (collecting && /^[a-zA-Z_-]+:/) { collecting=0 }
    if (collecting && NF>0) { desc=desc " " $0 }
  }
  END{ gsub(/[[:space:]]+/," ",desc); print desc }
' "$skill_md"

迷ったら Read で素直に読んで Claude 側で frontmatter を取り出す方が堅い。

4. README.md を生成

以下のテンプレートで $README_PATH を全文上書きする。冪等性のため、既存ファイルがあっても無条件に書き直す。

# ba2 チーム共有スキル

`skills/` 配下で**チーム共有**しているスキルの一覧。

このディレクトリは「配布元」であり、実際に使うには `ba2-skill-installer` で各自の個人ディレクトリ（`~/.claude/skills/` / `~/.codex/skills/`）に取り込む必要がある。

> このファイルは [`ba2-skills-readme`](./ba2-skills-readme/) スキルにより自動生成されています。手で編集しても、次回スキル発火時に上書きされます。各スキルの説明を変えたい場合は、対応する `<skill>/SKILL.md` のフロントマターを編集してください。

## スキル一覧

| スキル | 概要・トリガー | Codex 版 |
|---|---|---|
| [`<name>`](./<name>/) | <description 1行要約・実際には description をそのまま> | ✓ or 空欄 |
| ... | ... | ... |

> 「Codex 版」列の ✓ は `<skill>/.codex/SKILL.md` が同梱されていることを表す。`ba2-skill-installer` がそれぞれを `~/.claude/skills/` と `~/.codex/skills/` に振り分けてコピーする。

## 各スキルの詳細

### [`<name>`](./<name>/)

<SKILL.md 本文の最初の見出し直下にある説明段落（無ければ description をそのまま）>

- **トリガー例**: <description から抽出した「〜などのリクエストでトリガー」部分。無ければ省略>
- **Codex 版**: あり / なし

---

（以下、各スキルについて同じ形で列挙）

## メンテナンス

- スキルを追加・更新したら、このディレクトリの `.claude/settings.json` に仕込まれた PostToolUse hook が `ba2-skills-readme` スキルの実行を Claude に促し、自動で README.md が再生成されます。
- 手動で再生成したい場合は「ba2 skills の README を更新して」「ba2-skills-readme を走らせて」のように依頼してください。
- README の文面の手直しが必要な場合は、テンプレート自体（`ba2-skills-readme/SKILL.md`）を編集してください。

テンプレート埋め込みのコツ

• description はそのまま掲載。要約や言い換えはしない（フロントマターが「人間向けの説明 + トリガーワード」を兼ねているため、抜粋すると情報が落ちる）。
• 「トリガー例」は description の末尾にある「〜などのリクエストでトリガー」「〜などのリクエストで使用」のような句から抽出する。抽出規則は緩く：「『...』『...』のような句が並んでいたら箇条書きにする」程度でよい。抽出できなければ省略する。
• 本文の「最初の見出し直下の段落」は補足説明として有用なので、あれば詳細セクションに入れる。無ければ description をそのまま再掲してもよい（重複は許容）。
• スキルが 1 個も無い場合は「（まだスキルは登録されていません）」と書く。

5. 書き出し

組み立てた Markdown を $README_PATH に Write ツールで上書きする。

• ファイルが既存なら Read で前回内容を確認してから Write（Write のルール上必要）。
• 差分が無ければ Write をスキップしてもよいが、上書きでも実質ノーオプなので毎回 Write でも構わない（hooks 経由の発火を考えると無駄を避けたい場合はスキップ）。

6. 完了報告

• 何件のスキルを認識し、README にどのスキルを記載したかを 1〜2 行で報告する。
• コミットはしない。必要であれば人間が PR 経由で行う旨を伝える（自動コミットは hooks ループを誘発するため避ける）。

自分自身（ba2-skills-readme）の扱い

走査範囲は skills/*/SKILL.md なので、このスキル自身も一覧に含まれる。除外しない（メンテナとして可視化されている方が良い）。

hooks との関係

.claude/settings.json には PostToolUse hook が設定されており、skills/*/SKILL.md への Write / Edit を検知すると Claude に 2 つのスキル実行を促すメッセージを注入する:

1. ba2-skills-readme → skills/README.md を再生成
2. ba2-skill-installer → 配布元から個人ディレクトリへ反映

Claude はそれを見て両スキルを順次呼び出す（差分が無いものはスキップ）。

• 発火条件はファイルパスでフィルタしているので、skills/README.md への書き込み自体（このスキルが行う書き出し）は対象外。ループしない。
• hook が無い環境（個人 fork 等）でも、ユーザーが明示的に依頼すれば動くようにこのスキル単体で完結している。

注意事項

• このスキルが書くファイルは skills/README.md だけ。各 SKILL.md には絶対に書き込まない（無限ループの原因になる）。
• 冪等。既存 README は無条件に上書きしてよい。手編集は保持しない（テンプレートでカバーできない情報はフロントマターに移すこと）。
• コミット・プッシュは行わない。
• description が極端に長い場合でも改行・省略はしない（人間が読むに耐える長さ＝チーム運用上のガイドライン側で担保）。
• .codex/SKILL.md の内容は読まない（存在チェックのみ）。Codex 版固有の機能差分を README に書く必要が出たら、後でテンプレートを拡張する。

使用例

hooks 経由（自動）

1. メンバーが skills/foo/SKILL.md を新規作成・編集
2. PostToolUse hook が発火し、Claude に「ba2-skills-readme を実行して」と通知
3. このスキルが起動 → 全 SKILL.md を再走査 → skills/README.md を上書き

手動

ユーザー: 「ba2 skills の README を更新して」

実行:

1. skills/*/SKILL.md を全件走査
2. メタ情報を抽出
3. skills/README.md を再生成
4. 認識したスキル件数を報告