kulikala/wakariyasu

show-changes

変更前と変更後の差分を、1つ以上の対象(git のリポジトリの2つのコミット、2つのフォルダやファイル、既にある unified diff)にまたがって1つの HTML のページにし、人がブラウザで変更の全体と中身を確かめられるようにする。「差分を見せて」「変更を見せて」「変更内容を表示して」「変更をページにして」「レビュー用に差分をまとめて」と頼まれたとき、レビュー・承認・マージ・差し替えの前に人へ変更を見せるとき、複数のリポジトリやフォルダにまたがる変更をまとめて見せるときに使う。エージェントがファイルを…

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
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つの状態、分岐点から比べたか)と、全文を入れたかを短く添える。見る人が、ページに入っていない変更があるかを判断できるようにするため。
同じリポジトリから

関連する Skills

すべての Skills
kulikala
コミュニティ

check-terms

日本語の文書から、日本語では使わない言い回し(翻訳調の語や、作業の中で生まれた造語)と、文脈によっては別の語のほうが自然な言い回しを、一覧で探して替える。「言い回しを確かめて」「使わない語が無いか見て」と言われたときに使う。言われなくても、エージェントがファイルに記述した日本語の文書を人に渡す前に使う。wakariyasu の規則とほかのスキルも、言い回しの一覧と探すスクリプトをこのスキルのフォルダから使う。

1時間の導入数
1
GitHub Stars
0
更新日
11月9日
kulikala
コミュニティ

explain-clearly

エージェントが自分で作成した直前の返答や、返答の中の語・説明が分からないと言われたときに使う。「分かりやすく」「つまり?」「簡潔に」「どういうこと?」「言い換えると?」「平易に言うと?」「小学生でも分かるように」、返答に出た語について「〜とは?」、返答で並べたものについて「〜と〜の違いは?」と聞かれたときに当たる。ほかの言語で同じ意味のことを聞かれたときも当たる。作業の経緯を知らない人に通じる言葉で言い直し、言われた言葉から、短くまとめるか前提を足すかを選ぶ。返答と関係の無い一般の質問(「REST とは?」)は普段どおりに答える。セッションの進み具合を聞かれたら session-status を使う。

1時間の導入数
1
GitHub Stars
0
更新日
11月9日
kulikala
コミュニティ

session-status

「現状は?」「現在のステータスは?」「今何してる?」「どこまで進んだ?」「何が残ってる?」と聞かれたとき(ほかの言語で同じ意味のことを聞かれたときも)に使う。聞かれなくても、複数のタスクにまたがる作業が一区切りついて報告するとき、ユーザーに判断を求めて手を止めるとき、長い作業の途中経過を伝えるときに使う。今のセッションの状況を、現在のゴール・直近の指示・タスクの一覧(状態つき)・直近のステータスに分け、ユーザーに判断してもらうことがあれば番号つきの問いかけを添え、要点を絞って、背景と意図まで分かるように答える。

1時間の導入数
1
GitHub Stars
0
更新日
11月9日
kulikala
コミュニティ

summarize-session

今のセッションで扱った内容を、セッションに居なかった人やエージェントが後から読んで使える文書にまとめる。「このセッションをまとめて」「判明したことをまとめて」「指摘を抜き出して」と言われたときと、ほかの言語で同じ意味のことを言われたときに使う。依頼からユーザーが求めているものを推定し、頼まれた事柄を文書として構造化するドキュメント出力・分かったことを汎用的な知見として構成する知見抽出・ユーザーの指摘を指摘事項と意図と背景と対応方針で整理する指摘抽出・作業の記録を残すログ出力のうち、該当するモードの方針で文書を作る。複数のモードに該当すれば、モードごとに文書を分ける。どのモードにも該当しなければ、各モードの方針を参考に構成を組み立てる。返答の中で短く要約するだけのときには使わない。セッションの進み具合を聞かれたときは session-status を、直前の返答が分からないと言われたときは explain-clearly を使う。

1時間の導入数
1
GitHub Stars
0
更新日
11月9日