scrolls-help

Scrolls のヘルプ

このスキルの役割は、明確に回答して、余計なことをしないことです。ユーザーのコードベースを調べたり、Scrolls がここで実際に設定されているか確認したり、ユーザーのプロジェクトに変更を加えたりはしません。

対象範囲に関する注記： このスキルは、/scrolls-help リクエストへの対応中に、ユーザーのコード、ユーザーファイル、または自身のディレクトリ外のものに書き込むことはありません。自身の references/HELP.md を最新の状態に保つことは、スキルのメンテナンス担当者が行う、これとは別の無関係な保守作業です。詳しくは meta/MAINTAINERS.md をご覧ください。ユーザーへの回答中に行う作業ではありません。ファイルシステムの対象範囲、ローカルの -e／--online サーバーのネットワーク公開範囲とライフサイクルを含む、セキュリティ対策の全容については meta/SECURITY.md をご覧ください。これは参考資料であり、リクエストへの回答中に実行する作業ではありません。

クロスプラットフォーム

-e／--online のランチャーには、open_help.sh（bash — macOS、Linux、または Git Bash／WSL を使用する Windows）と open_help.ps1（PowerShell 7 以降 — Windows、または pwsh をインストールした macOS／Linux）の 2 種類があります。両方のランチャーが起動する実際のサーバーである serve_help.py は、移植作業が一切不要です。Python の標準ライブラリのみを使用しているため、すでにクロスプラットフォームで動作し、どちらのランチャーも同じ方法で呼び出します（python3 を解決し、次に python にフォールバックします。Windows では通常、後者のみが PATH にあります）。実際に利用できるランチャーを選んでください。まず bash --version を試し、成功した場合は .sh を使用します。そうでない場合は、pwsh を使って .ps1 を実行してください（推奨。見つからない場合は https://aka.ms/powershell からインストールしてください）。pwsh が本当に利用できない場合に限り、Windows に組み込まれている Windows PowerShell の powershell.exe を使用してください（古いバージョンでは未テストです。このスクリプトは pwsh を前提に作成・検証されています）。

オプション

呼び出し時のテキストに、任意の -e／--online が含まれているか確認してください。これを指定すると、チャットで回答する代わりに（またはユーザーの意図が曖昧な場合は、回答に加えて）、references/HELP.md をスタイル付きの HTML ページとして表示し、ローカルで配信します。リクエストの解釈方法（引数なしの呼び出しか、具体的な質問かなど）は、このフラグの有無にかかわらずまったく同じです。-e が変更するのは出力先のみです。

手順

1. references/HELP.md を読みます。これはメンテナンスされている正規の内容です。これらのスキルの仕組みについての記憶から説明を再構成するのではなく、その内容を提示してください。フラグの意味は反復的な変更の中で変わっています（例：以前は -r が「リポジトリのルート」を意味していましたが、現在は「再帰」を意味します）。そのような変更があったときに更新される唯一の信頼できる情報源は、この参照ファイルです。

2. -e/--online が指定された場合：bash <skill-dir>/scripts/open_help.sh または pwsh <skill-dir>/scripts/open_help.ps1 を実行します（上記の「クロスプラットフォーム」を参照）。依存関係のインストールが不要な、標準ライブラリのみを使用する小さな Python サーバーを起動します。このサーバーは HELP.md を、すっきりとした自己完結型の HTML ページにレンダリングし、OS が割り当てたポートで 127.0.0.1 にバインドします（すべてのネットワークインターフェイスにはバインドしません。これはローカルのリファレンスビューアーであり、ネットワークに公開するものではありません）。スクリプトは、サーバーが実際にリッスンしていることを確認してから出力します。その後、URL とプロセスの PID を出力します。その URL をクリック可能なリンクとしてユーザーに伝えてください。このスキルの終了後もサーバーは実行され続けるため、リンクは引き続き開けます。また、アイドル状態が 30 分、または合計 2 時間（いずれか早い方）で自動的に終了すること、および <script> --stop <port>（またはすべてのインスタンスを停止するには --stop --all）で早めに停止できることを伝えてください。PID を探して手動で kill する必要はありません。-e を指定して新たに実行すると、既存のサーバーを再利用せず、新しいポートで別のサーバーが起動します。長いセッション中に複数のインスタンスが起動する可能性がある点は知っておくとよいでしょう。停止を指示されなくても、それぞれ自動的に停止します。スクリプトによるブラウザーの起動が目に見える形で動作しなかった場合（たとえば、ディスプレイのないヘッドレス環境やリモート環境）は、想定どおりです。URL は引き続き有効なので、ユーザーへの報告が重要です。

   ページの右上には、小さなツールバーがあり、互いに独立した 2 つの切り替えボタンがあります。ライト／ダーク（デフォルトではシステム設定に従います。ボタンで明示的に切り替えられ、その設定は localStorage に保存されます）と、色付き／プレーン（デフォルトでは、コードブロックに GitHub のシンタックス表示風の小さな配色が適用されます。コマンド、フラグ、コメントはそれぞれ異なる色で、ライトモードとダークモードでは別の色が使われます。Pygments／pymdown-extensions のテーマをイメージした配色です。ボタンを押すとプレーンテキスト表示になり、こちらの設定も保存されます）です。URL を伝える際には、どちらの切り替え機能もあることを伝えてください。リンクだけでは分かりにくいためです。

3. -e を付けない単独の /scrolls-help、または範囲を限定しない質問（「scrolls のコマンドは何ですか」「これはどのように動きますか」など）の場合は、ドキュメント全体を Markdown のチャット出力として提示します。これは回答であり、成果物ではありません。ユーザーから別途依頼がない限り、ファイルに書き出したり、成果物として公開したりしないでください。

4. 特定の質問（1 つのコマンド、1 つのフラグ、「モノレポでこれを行うには」のようなシナリオ、または単独で言及されたコマンド名）の場合は、まずドキュメント内の該当箇所を簡潔に回答し、残りは単独の /scrolls-help で確認できることを伝えます。実際に尋ねられた内容にかかわらず、リファレンス全体を提示してはいけません。これは -e が指定されている場合にも適用されます。-e によって変わるのはドキュメント全体の提示先であり、特定の質問にはまずその質問に絞って回答する点は変わりません。

5. リファレンスファイル本来の語調と書式を保ったまま提示してください（チャットでもレンダリングされたページでも同様です）。すでに簡潔に書かれているため、個人的な意見を加えたり、冗長にしたり、明確に書かれた内容を再説明したりしないでください。

開発

references/HELP.md の最新状態を保つ方法、および tests/ の回帰テストスイートの実行方法については、meta/MAINTAINERS.md を参照してください。ユーザーの /scrolls-help リクエストに対応する際、どちらも読む必要はありません。回答中に meta/MAINTAINERS.md や tests/ を参照したり、操作したりしないでください。