wiki-smith — リポジトリの .wiki/ を管理する
Wiki はリポジトリのメモリであり、エージェントのために書かれます。エージェントはここでルールを見つけるため、毎回同じことを尋ねる必要がありません。日記には「起こったこと」を、トピックページには「現在成立していること」を記録します。日記だけに残っている教訓は失われます。wiki-smith は、セッションにどちらが必要かを判断し、この Wiki 自身のルールに従って書き、チェックします。
完全なメソッド（ファイル形式、ノートのフォーマット、取り込み、リンク、日付、コミット）: references/method.md。設定キー: references/config.md。クレジット: ATTRIBUTION.md。変更履歴: CHANGELOG.md。自身のメモリ: .wiki/。
以下の <skill> はこのスキルのフォルダ（例 ~/.claude/skills/wiki-smith）を指します。すべてのスクリプトは -w <wiki dir>（デフォルト ./.wiki）と -c <config>（デフォルト <wiki>/wiki.config）を受け取ります。
ステップ 0 — Wiki とそのルールを見つける
- Wiki はリポジトリルートの
.wiki/です。存在しない場合はその旨を伝え、templates/ から作成を提案します（最初はwiki.config.example）。許可なく作成してはいけません。 .wiki/wiki.configが存在すれば読み込みます（名前: 日記フォルダ、受信箱、インデックス、フッターラベル、日付キー、メインブランチ）。デフォルトは汎用的な英語です:journal/、inbox.md、index.md、Map:、## History、created/updated。- Wiki 自身のルールが優先されます。 リポジトリにメンテナンス方法に関するページ（
rg -n -i 'メンテナンス|管理' .wiki -l）や、Wiki に関するAGENTS.mdルールがあれば、そのセクションを読み、このスキルと異なる部分はそれに従います。 - ユーザーが「wiki update」を要求し、Wiki（通常はインデックス）が「最初に確認する」と指示している場合、ステップ1とステップ2を計画としてのみ実行します。変更内容、新規ノートのタイトルを1行ずつ表示し、「Apply?」と尋ね、承諾があった場合のみ編集します。それ以外の場合は即座に実行します。
ステップ 1 — 何が起こったかを確認し、ルーティングする
セッション（および git diff、git log で行われた作業）を読み取ります。該当するすべての行を選択し、それ以外は選択しません:
| セッションの内容 | 実行すること |
|---|---|
| 決定、納品、方針転換、インシデント、調査 | 日次ノート: scripts/note.sh -b 「変更点を表すタイトル」 に本文をパイプで渡します。その後、受信箱にその日の行を追加します。 |
| 現在も有効なルール、教訓、事実 | トピックページも修正: 現在成立しているルールのみを記載し、履歴は含めません（履歴はノートとページの History セクションに残します）。ページの以前の記述を訂正し、「以前は...だった」のような積み重ねは避けます。 |
| 複数の側面を持つ新しいテーマ（再登場する可能性があり、1ページに混在させると不適切な場合） | コンテンツマップ moc-<トピック>.md と、個別のページ <トピック>-<側面>.md（チートシート、インストール、統合、現在のツールとの比較など）。下記「新しいテーマ」を参照。 |
| 記録する価値がないもの（中間ステップのみ、またはコミットで既に述べられていること） | 1行でその旨を伝え、何も作成しません。日記を水増しすると読みづらくなります。 |
日記には常に新しいノートのみを作成します。他のエージェントのノートを書き換えてはいけません。
ステップ 2 — 記述する
日次ノート。 scripts/note.sh "<タイトル>" は <DIARY_DIR>/<今日>/<HHMM>-<スラグ>.md を UTC で作成し、そのパスを出力します（スラグルールと衝突時の -2 の動作はスクリプト内に定義）。標準入力は -b 付きでのみ読み取られます: エージェントシェルと CI は標準入力を開いたままにするため、-b がないとスクリプトは永遠に待機します。本文をパイプで渡すには: printf '%s\n' "<段落>" | scripts/note.sh -b "<タイトル>"。-b はタイトルと本文の間に正確に1行の空行を挿入します。-b がない場合、ファイルはタイトル行のみです。後から段落を追加するには、空行で始めます: printf '\n%s\n' "<段落>" >> "$path"。本文は1つのよく書かれた段落です: 何が起こったか、なぜ重要なのか、証拠（コミット、PR、Issue）はどこにあるか、トピックページへのリンクを含めます。リンクは日付フォルダからの相対パスです（../../page.md）。テンプレート: templates/note.md。
その日の最初のノート: scripts/day-index.sh でその日のインデックスを作成し、受信箱の「最近の日付」の先頭にその日を追加します。ノートによってリポジトリの動作が変わる場合は、受信箱のハイライトにも1行追加します。受信箱自体にノートの内容を保持してはいけません。
トピックページ（取り込み）。 該当ページを検索します（rg -n -i '<単語>' .wiki）。存在せず、テーマが再登場する場合は作成します（テンプレート: templates/page.md）。ページが小さい場合は、近くのページのセクションに配置します。現在成立しているルールを記述します。変更によってページの主張が変わる場合は、History セクションの先頭に1行追加します。ノートから該当ページへのリンクを張ります。
新しいテーマ。
- まず個別のページを、各側面ごとに1つずつ、最初の文から自己完結する形で書きます。典型的な側面: チートシート（最初に作成する: アドレス、コマンド、ショートカット）、インストール、統合、現在使用中のツールとの比較。
moc-<トピック>.mdを作成します（templates/moc.md）: 導入段落、「ページ一覧」（各行1ページ、チートシートを最初に）、「最初に知っておくべきこと」（特に注意すべきルールをいくつか）。- すべてのページにフッター（
Map: [moc-<トピック>](moc-<トピック>.md) · Related: ...）を付け、マップと各ページをインデックスに追加し、少なくとも1つの他のマップからこのマップへのリンクを張ります。 - 日記にノートを作成し、何を作成したかとマップへのリンクを記述します。
ステップ 3 — クローズ（常にこの順序で）
scripts/dates.sh—created/updatedのフロントマターを Git の情報から設定します。冪等です。scripts/day-index.sh— 日次インデックスを再生成します。手動で編集してはいけません。python3 -I scripts/lint.py— 出力されるすべてのfile:line: type: messageを修正し、終了コード0になるまで繰り返します（終了コード2は問題あり）。赤いリンターエラーを出してはいけません。- 自ファイルのみを、パスを指定してコミットします。
git add -Aは絶対に使わず、scripts/sync.sh -m "wiki: <内容>" <パス>...を使用します。チェックアウトが<main>ブランチにあり、最新で、自パス以外に変更がない場合はその場でコミットします。そうでない場合は、自パスをorigin/<main>からの新しいgit worktreeに運びます。どちらの場合も、コミットする内容を正確に lint し、赤いリンターエラーを拒否します（終了コード1、チェックアウトはそのまま、worktree は削除）。運ぶ場合、生成された日次インデックスはコピーされません。worktree 内で再生成されるため、コミットに含まれるノートのみがリストされます。リポジトリやホストが要求する帰属行をコミットメッセージに追加します。- 他のセッションも編集した可能性がある共有ファイル（インデックス、受信箱）: これらを運ぶ処理に渡してはいけません。
scripts/sync.sh -Wはorigin/<main>からの新しい worktree を出力します。そこで編集を行い（Wiki は同じ相対パスにあります）、dates.sh、day-index.sh、lint.pyを実行し、その worktree 内でsync.sh -m ... [-p] <パス>を実行します。そこでコミットし、-p付きの場合は rebase、プッシュ、メインチェックアウトを可能な限り fast-forward し、worktree を削除します。他のセッションの行（例えばチェックアウトにしかないページへのリンク）を誤って運んでしまうと、lint が失敗し、コミット前に処理が停止します。その失敗が-Wを使うべき合図です。
- 他のセッションも編集した可能性がある共有ファイル（インデックス、受信箱）: これらを運ぶ処理に渡してはいけません。
- ユーザーが同期を要求した場合のみプッシュします: 同じ呼び出しに
-pを付けて実行します（fetch、rebase、push HEAD:<main>、チェックアウトを fast-forward、worktree を削除）。強制プッシュは決して行わず、他の人の変更ファイルには触れません。プッシュした内容と異なり、他のセッションの編集が含まれる可能性があるファイル（インデックス、受信箱）はそのままにします。チェックアウトを fast-forward できない場合（ローカルの<main>が分岐している、またはローカルの編集が重複している）はその旨を伝え、それでも終了コード0で終了します（プッシュは成功しているため）。PR は要求された場合のみ開きます。
同じセッションで書いた内容は、要求を待たずにコミットします。公開するかどうかはユーザーの判断です。
Wiki の参照
rg -n -i '<キーワード>' .wiki（またはインデックスをざっと見て）該当するページまたはセクションのみを読みます。Wiki 全体を読むことはしません。何が起こったかを調べるには: 受信箱（簡潔）、次に関連する日だけを読みます。1日分 = その日のインデックスと、そこにリストされたノートです。リポジトリに仕様書があれば、システムが約束する内容が書かれています: rg -n -i '<キーワード>' <仕様ディレクトリ>。
落とし穴
- 日記はページではない。 ノートにしか書かれていないルールは失われます。同じセッションでトピックページに取り込みましょう。
- 履歴のないルール。 「カードを作成する前に、既存のものを検索する」と書き、「以前はカードを重複させていた」とは書きません。履歴はノートに残します。
- 1ファイルに1ノート。 複数のエージェントが同じ日に書き込む場合、同じファイルを編集してはいけません。日次インデックスは生成されるため、競合は
day-index.shを再実行することで解決します。 - セッション間での共有ファイル。 日次インデックス、
index.md、受信箱には、1つのチェックアウト内のすべてのセッションの未コミット編集が保持されます。sync.shは日次インデックスを運びません（worktree 内で再生成します）。コミット前に lint を実行しますが、手動編集されたindex.mdや受信箱のどのハンクが自分のものかを区別できません。運ぶ処理は差分全体を取ります。他のセッションがこれらのファイルに触れた可能性がある場合は、sync.sh -Wを使用して worktree 内で編集してください。たまたま lint を壊さない外部の行でも、運ばれる可能性があります。これが運ぶ処理の文書化された限界です。 - 標準入力で待機しない。
note.shは-b付きでのみ本文を読み取ります。エージェントシェルで何も指定せずに読み取ろうとすると、永久にブロックします。これは追加するすべてのスクリプトに当てはまります。 - 一時的なものを記録しない。 一度失敗したが再試行で成功したコマンド、環境の不具合、一回限りのタスクなど。動作する修正はトピックページに記録し、決して「X は壊れている」とは書きません（原因がなくなった後も拒否として残ってしまうため）。
- リンク: 相対パス、セクション内で最初の出現時にのみリンクを張ります。アンカーは GitHub の見出しスラグです（小文字、句読点なし、アクセントは保持、スペースはハイフン）。見出しの名前を変更するとアンカーが壊れます。lint がそれを警告します。バッククォート内にリンク例を入れると、lint が読み取らなくなります。
- ページのリネームまたは削除:
rg -l '旧名' .wikiですべてのリンク（アンカーを含む）を修正し、コンテンツを移動した後にのみ削除します。 - ページサイズ: 約150行を超える場合、またはルール、手順、リファレンス、履歴が混在する場合は、種類ごとに分割します。
- プライベートデータは外部に残す。 Wiki ページはコミットされます。シークレット、トークン、個人データは含めず、代わりにシークレットの保存場所を参照します。
- Lint の制限: ページ間の矛盾や古い主張は検出しません。それは時間があるときのエージェントのレビューに委ねられます。
day-index.shの制限: 手書きの古い形式のノートを含む日付ファイルはエラー（file:line）になります。移行はされません。各ノートをnote.shで個別のファイルに移動し、再実行してください。
ステップ 4 — 自分自身の Wiki を維持する
この実行で wiki-smith 自体の運用に関する教訓（ルーティングのミス、スクリプトの癖など）が得られた場合、.wiki/lessons.md に1行追加します: - YYYY-MM-DD — <ルール + 理由>。ソースクローン（biliboss/wiki-smith）を編集し、再インストールします（npx skills add biliboss/wiki-smith -g --copy -a claude-code -y）。インストール済みのコピーを直接編集してはいけません。再インストールで上書きされるためです。設計上の決定は .wiki/design.md に記録します。