alanchoi00/citing-sources-with-excerpts

抜粋付きでの出典引用

概要

引用された主張はすべて、その証拠（該当箇所の逐語的な文章、その箇所にジャンプしてハイライトするリンク、およびオプションでスクリーンショット）をインラインに含みます。読者はクリックしなくても確認でき、クリックすればテキストの正確な位置に移動します。Markdownファイルとチャット回答の両方で機能します。

すべての引用は、snap.mjs の出力から取得しなければなりません。記憶、検索結果の要約、または要約を生成する fetch ツールから引用してはいけません。 検索の要約や WebFetch 形式のツールはページを言い換えます。このスクリプトだけがレンダリングされたテキストを逐語的にチェックします。

引用だけでなく、主張も確認してください。 一致する引用は、そのページがその内容を述べていることを証明します。ページが述べていないことについては何も証明しません。以下の2種類の主張は、たとえ「下書きの確認」だけを行う場合でも、常にスクリプトの個別のバッチエントリとして処理する必要があります。

• 不在: ページが何かを述べていない、言及していない、または必要としていないと書く前に、もし書かれていたであろう文章を追加してください（例: Responses with the 429 status code MUST NOT be stored by a cache.）。match: none のみが不在を裏付けます。その後、「<ページ>には見つかりませんでした」と書き、「仕様はXについて何も述べていない」とは決して書かないでください。
• 矛盾: 記憶、検索の要約、既に作成した下書き、またはこのスキルの例が、ページの内容について異なることを述べている場合、矛盾している文章を追加してください。スクリプトの結果がそれを解決し、どちらの立場を支持するかにかかわらず優先されます。（このスキルの例のすべての引用は、スクリプトで検証されています。）

セットアップ（各マシンで一度だけ）

npm install --prefix <skill-dir>/scripts && npx --prefix <skill-dir>/scripts playwright install chromium

<skill-dir> はこの SKILL.md を含むディレクトリです。

スクリプト

最初にドキュメントまたは回答を作成し、すべての引用を収集してから、それらをすべて一度のバッチ呼び出しで 検証します。

node <skill-dir>/scripts/snap.mjs --batch - <<'EOF'
[
  {"url": "https://www.rfc-editor.org/rfc/rfc6585.html", "quote": "Responses with the 429 status code MUST NOT be stored by a cache."},
  {"url": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After", "quote": "A non-negative decimal integer", "out": "/abs/path/docs/refs/delay.png"}
]
EOF

バッチ全体で1つのブラウザを使用します。同じURLの引用はページ読み込みを共有します。out には絶対パスを使用してください。入力は {"defaults": {...}, "cites": [...]} として、スクリーンショットオプションをすべてのエントリに適用することもできます。バッチ出力は入力順のJSON配列です（単一モードの snap.mjs "<url>" --quote "..." は1つのオブジェクトを出力します）。各エントリ:

フィールド	使用方法
ok / match	exact/loose = 逐語一致。fuzzy = 引用が間違っていました。代わりに quote_on_page を使用し、主張がまだ有効かどうかを再確認してください。none = ページ上にありません。
quote_on_page	ブロック引用に配置するテキスト。元の --quote は絶対に使用しないでください。
fragment_url	使用するリンク（#:~:text= を含み、Chrome/Safari/Firefox でハイライト表示されます）。
excerpt	周辺の段落。文脈（否定、但し書き、「～を除く」など）を確認するために使用します。もっと長く引用したいですか？その長い文章を --quote として再実行し、リンクとスクリーンショットを一致させてください。
title, section, retrieved	帰属行: [<title> — <section>](fragment_url) · retrieved <date>、または section がない場合は [<title>](fragment_url)。これらのフィールドを使用してください。記憶からセクション番号を追加しないでください。
occurrences / occurrence	引用が複数回出現する場合に表示されます。excerpt が意図したものであることを確認してください。違う場合は、prefix/suffix（ページ上でその直前/直後の単語）を指定して再実行してください。
hidden	引用がページが非表示にしているコンテンツ（例: 非アクティブなタブ）にあります。検証済みですが、スクリーンショットはありません。
note	知っておく価値のあるその他の情報（あいまい一致、展開された折りたたみセクション、フレームのフォールバック）。必ず読んでください。
internal	ページが内部ネットワーク上にあります。その内容は機密である可能性があります。主張に必要な以上に引用しないでください。

終了コード 0 = すべて見つかった、1 = 一部見つからなかった、2 = 一部エラー（PDF、4xx、ログイン壁、ボットチェック、タイムアウト）。1回のフォローアップバッチを想定してください。もう一度処理が必要なエントリ（失敗、あいまい一致、間違った出現、またはより長い文章が必要）をすべてまとめて投入してください。

スクリーンショットオプション

任意のエントリ（または defaults 内）のオプションフィールドです。ユーザーの表現に合わせてマッピングしてください。特に指定がない場合は、これらを省略します。

ユーザーの指定	フィールド
「タイトなスクリーンショット」、「引用だけ」	"frame": "quote"（デフォルトは paragraph）
「セクション全体を表示」	"frame": "section"（高さの上限が自動的に1200に上がります）
「全画面」、「ページの周囲を表示」	"frame": "viewport"
「その前後の数行」	"context": 2（上下のテキスト行全体）
「モバイルサイズ」	"width": 390（デフォルトは1100）
「短くして」	"max_height": 150（デフォルトは500。切り抜きは引用を中心にします）
「黄色でハイライト」、「ハイライトなし」	"highlight": "#fff3a0" / "none"
「ダークモード」	"theme": "dark"（ダークテーマを持つサイトのみ。note にそうでないと記載されます）
「小さめの画像」	"scale": 1（デフォルトは2）

これらはスクリーンショットのみを整形します。テキスト自体に文脈が欲しい場合（またはスクリーンショットがない場合）は、excerpt から取得したより長い文章を引用し、フォローアップバッチで再実行してください。表のセル内の引用は、自動的にその行とヘッダー行をフレームに収めます。すべてのオプションとそのスクリーンショットは、リポジトリの examples/README.md にあります。

出力形式

テキストを配置する場所に応じて形式を選択します。

Markdown ファイル: 主張を散文に、証明を脚注に:

クライアントはレート制限応答をキャッシュすべきではありません。[^429-cache]

[^429-cache]: > Responses with the 429 status code MUST NOT be stored by a cache.
    >
    > — [Additional HTTP Status Codes — 4. 429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585.html#:~:text=Responses%20with%20the%20429%20status%20code%20MUST%20NOT%20be%20stored%20by%20a%20cache.) · retrieved 2026-11-08
    >
    > ![RFC 6585: 429 must not be cached](refs/429-cache.png)

• 脚注IDは番号ではなく、短く説明的なスラッグにします。同じ文章が2つの主張を裏付ける場合は、同じ [^id] を再利用します。
• スクリーンショットはMarkdownファイルの隣の refs/ に保存します。ファイル名 = 脚注スラッグ。削除した引用のPNGは消去します。

チャット回答: 脚注は使用しません（ターミナルでは生のテキストとして表示されます）。証明を、それが裏付ける主張の直下に配置します:

クライアントはレート制限応答をキャッシュすべきではありません:

> Responses with the 429 status code MUST NOT be stored by a cache.
> — [Additional HTTP Status Codes — 4. 429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585.html#:~:text=Responses%20with%20the%20429%20status%20code%20MUST%20NOT%20be%20stored%20by%20a%20cache.)

• retrieved 日付は不要です（回答自体が検索時点です）。
• チャットのスクリーンショットはシステムの一時ディレクトリ（例: $TMPDIR/receipts/<slug>.png）に保存し、決してユーザーのプロジェクト内には保存しません。ホストがユーザーにファイルや画像を表示するツールを持っている場合は、各スクリーンショットをそのツールで表示します。そうでない場合は、引用の後に各行にそれぞれの完全な絶対パスを記載します。
• スクリーンショットが要求されていない場合 → 回答の最後に「これらの引用のスクリーンショットが必要ですか？」のような1行の提案を追加します。

両方に共通:

• あなた自身の推論や推奨には引用は不要です。それがあなた（またはチーム）の推論であり、出典のものではないことを明記してください。外界（ライブラリ、ブラウザ、標準の動作）に関する事実上の主張には引用が必要か、「～と期待される」という形で表現する必要があります。
• スクリーンショットはオプトインです。安価（ページあたり約0.5秒）ですが、ユーザーが保持または削除する必要のある画像ファイルが増えます。"out" は、ユーザーがスクリーンショットを要求した場合、またはMarkdownファイルにおいて、証拠が視覚的（表、図、コードレイアウトなど）でテキストだけでは意味をなさない場合にのみ追加してください。結果に screenshot が含まれるエントリに対してのみ、画像またはパスを含めてください。
• 主張を完全に裏付ける最短の文章を引用してください（通常は1文）。

スクリプトが失敗した場合

結果	対応
match: fuzzy	quote_on_page を使用してください（スクリーンショットは既にそれをハイライトしています）。それがもはやあなたの主張を裏付けない場合は、主張を変更してください。
match: none	別の方法でページを検索してください（別の文章、別のセクションURL）。それでも見つからない場合 → 主張を削除するか、プレーンなリンクとともに **UNVERIFIED:** とマークしてください。未検証の引用をブロック引用として提示しないでください。
ok: false + エラー（PDF、ログイン壁、ボットチェック、403）	プレーンなリンク + **UNVERIFIED (could not load: <error>)**。記憶やWebFetchから引用をでっち上げないでください。
occurrences > 1 かつ excerpt が間違っている	意図したものの前後の単語を "prefix" または "suffix" に設定して再実行してください。

よくある間違い

• ページが「基本的に言っていること」を引用する → ブロック引用は逐語のみ。言い換えは散文に記述します。
• fragment_url の代わりにセクションアンカー（#section-4）を使用する → 読者は依然として探す必要があります。
• その excerpt が主張と矛盾する文章を引用する（例: 次の文が「これは～には適用されない」と述べている）。
• 「検証」のためにWebFetchを実行する → 要約するだけであり、逐語テキストを確認できません。スクリプトを使用してください。
• 検索ツールの回答要約がページの内容や欠落について述べていることを信頼する → WebFetchと同様に言い換え、どのセクションが何を言っているかを誤って伝えることがよくあります。矛盾している文章をスクリプトにかけてください。
• 下書きに既にある引用だけをチェックして「検証」する → 不在の主張や矛盾する主張がテストされないため、誤った回答があたかも完全に検証されたように見えます。