使い方
- インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
- 必要なツール、認証情報、対応環境を原文で確認します。
- 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/kulikala/wakariyasu --skill show-changes開始前の確認
- 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
- スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。
スキルの目的
変更前と変更後の差分を、ブラウザで開く1つの HTML のページにする。ページを見る人(レビューや承認をする人。依頼したユーザー自身のこともある)が、何がどれだけ変わったか(全体)と、どう変わったか(中身)を、リポジトリやフォルダをまたいで1か所で確かめられるようにする。ページは変更を見せるためのもので、変更の良し悪しは判断しない。呼び出し元は、このスキルを頼んだユーザー、またはこのスキルを呼んだエージェントだ。
ページは同梱の scripts/build.py で作る。Python 3.9 以上(python3 などのコマンド)がある環境では build.py を実行してページを作り、無い環境では、ページを作れないことを呼び出し元に伝える。ページを作る前に、呼び方と引数を記載した references/usage.md を読む。スキルの中のパス(scripts/・references/)は、このスキルのフォルダからの相対パスで記述してある。
比較対象の指定
- 見る人が確かめたい変更に合わせて、比べる対象の種類を選ぶ。git で管理している変更なら2つのコミット、git で管理していないファイルの前後(変更前に控えた複製と今のもの、2つの版のフォルダなど)なら2つのフォルダ、ほかのツールが作った差分ならその unified diff を比べる。種類は1つのページの中で混ぜられる。
- ブランチの変更を見せるなら、取り込み先のブランチとの分岐点からブランチの先までを比べる(
--merge-base)。取り込み先のブランチに後から入った変更が、ページに混ざらない。 - git の2つのコミットで比べられるのは、コミットされた変更だけだ。作業中の変更をコミットするかはユーザーが判断する。コミットしていない作業中の変更を見せるなら、
git diff HEADの出力を unified diff として渡すか(git にまだ追加していない新しいファイルは入らない)、変更前の複製と今のものを2つのフォルダとして比べる。2つのフォルダの比較は、git が無視するファイル(依存物・ビルドの出力・接続情報のファイルなど)も比べるので、比べるフォルダには見せたいファイルだけを入れる。 - unified diff の対象は差分に記載された行の範囲しか持たない。ファイルの全文を見せたいときは、ほかの種類の対象にする。
- ページの題とデータの版(
--data-version。ページのヘッダーにそのまま出る文字列)は、見る人が何を見ているかを後から言えるように付ける。題には何の変更か、データの版には比べた状態(コミット・日付・版の名前)が分かるものを入れる。
全文表示の選択
全文を入れると、見る人は変わった行の前後だけでなく、ファイル全体の流れの中で変更を読める。その代わり、ページは変わったファイルの大きさの分だけ大きくなる。依頼から、見る人が前後の流れまで読む必要があると読めるとき(文書の書き直し、設定ファイルの一部の変更など)に全文を入れ、変更の量や箇所を見るだけなら差分だけにする。どちらとも読めなければ差分だけにし、全文を入れたページも作れることを渡すときに添える。
出力ファイルの提示方法
ページは、見る人がその場で開いて見られる形で渡す。HTML ファイルを作って保存先や添付を示すだけでは、見る人がファイルを取り出して開くまでページを見られない。Claude が動く環境では、ページをアーティファクトとして示すことを既定にする。
- ローカルの HTML ファイルをそのままアーティファクトとして公開できるツールがあれば、作ったファイルを公開する。Claude のアーティファクトは公開するときにページに文書の骨組み(DOCTYPE・html・head・body)を付けるので、
build.pyに--artifactを付けて、骨組みを省いて書き出す。ページには差分のデータがすべて入っていて大きくなることがあるので、ページの中身を書き写さずにファイルのまま公開する。 - アーティファクトを中身から作る環境(ファイルを公開するツールが無く、アーティファクトの中身をエージェントが記述する環境)では、
build.pyが書き出したページを、書き換えずにアーティファクトの中身にする。手で書き換えると、ページの差分が元の変更と合わなくなる。ページが大きく中身にしきれないときは、全文を入れないページにする。 - アーティファクトを使えない環境では、HTML ファイルを保存して、ファイルの場所を呼び出し元に伝える。保存する場所を呼び出し元が言っていなければ、比べるどのリポジトリやフォルダにも入らない場所に置く。比べる対象の中を出力先にすると、
build.pyは止まる。 - 公開先に大きさの上限があってページが上限を超えるなら、全文を入れないページにするか、HTML ファイルで渡す。
build.pyは、出力先に同じ名前のファイルがあっても、確かめずに上書きする。人が開いているページや、人が手を入れたページと同じ名前にしない。- 公開したページは外部のサービスに置かれる。ユーザーが秘密として扱っている対象や、持ち主が外へ出すことを認めていない情報がページに入っていそうな対象なら、公開せずに HTML ファイルで渡し、どこに置くかは呼び出し元に任せる。差分だけのページには変わった行とその前後の数行とコミットの件名が入り、全文を入れたページには変わったファイルの変わっていない所も全部入る。
- 渡すときは、何と何を比べたか(対象、比べた2つの状態、分岐点から比べたか)と、全文を入れたかを短く添える。見る人が、ページに入っていない変更があるかを判断できるようにするため。