credentials

安全な認証情報プロトコル

多くのスキルでは、機能の利用や、より高いレート制限へのアクセスに API キーなどの認証情報が必要です。このスキルでは、機密性の高いキーをエージェントのコンテキストや会話履歴に漏らさずに、認証情報の有無を確認し、入力を促すための標準的な安全プロトコルを定めています。

安全な確認（漏えいなし）

認証情報または API キーを必要とするスキルがユーザーのリクエストに関連しそうだと判断したら、そのスキルに関するほかの作業を始める前に、.env ファイル（通常はホームディレクトリの ~/.env またはプロジェクトのルートにあります）に認証情報があるかどうかを直ちに確認しなければなりません。

重要：認証情報の値をターミナルに出力したり、コンテキストに読み込んだりせずに、認証情報の有無を確認してください。

確認方法：

grep を quiet モードかつエラー抑制モード（-sq）で使い、~/.env に変数が定義されているかを確認します。-s フラグを使うと、~/.env がまだ存在しない場合でもコマンドを問題なく実行できます。

grep -sq "^CREDENTIAL_NAME=" ~/.env

CREDENTIAL_NAME を、呼び出し元のスキルで必要な実際の認証情報名（例：ALPHAGENOME_API_KEY または USER_EMAIL）に置き換えてください。

• コマンドが成功した場合（終了コード 0）、認証情報は存在します。続行できます。
• コマンドが失敗した場合（認証情報がない、または .env ファイルがまだ存在しないなど、終了コードが 0 以外の場合）、認証情報がありません。スクリプトやツールの実行を試みる前に、直ちに作業を止めて、認証情報を追加するようユーザーに促すの手順に従ってユーザーに入力を促さなければなりません。キーがないと伝えるだけでターンを終了してはいけません。

[!CRITICAL] 確認に失敗した場合（終了コードが 0 以外の場合）、呼び出し元のスキルのツールやスクリプトを実行しようとしてはいけません。また、キーがないと伝えるだけでターンを終了してもいけません。以下のテンプレートから適切なターミナルコマンドを直ちに生成し、ユーザーに実行するよう促さなければなりません。テンプレートのコマンドは、まだ存在しない場合に .env ファイルを作成します。

認証情報を確認するために、cat ~/.env、grep "VAR" ~/.env（-q なし）、echo $VAR、または printenv を実行してはいけません。

認証情報を追加するようユーザーに促す

認証情報がない場合、ユーザーにチャットへ貼り付けるよう求めてはいけません。認証情報の値がエージェントのコンテキストや会話履歴に漏れるためです。

代わりに、以下のテンプレートのいずれかにあるプレースホルダーを置き換えて、ユーザーがターミナルで実行するための具体的なコマンドを生成しなければなりません。

重要：ユーザーにコマンドを提示する前に、以下を置き換えなければなりません。

• CREDENTIAL_NAME を必要な実際の変数名（例：ALPHAGENOME_API_KEY、USER_EMAIL）に置き換えます。
• ENV_FILE を .env ファイルの解決済みの絶対パス（通常は ~/.env）に置き換えます。

テンプレート

すべての認証情報は機密情報として扱います。read -s フラグを使うと、ユーザーの入力が画面に表示されません。入力内容が表示されないことをユーザーに伝えなければなりません。

重要：認証情報の入力を求める際は、値を取得する方法がわからない場合にユーザーが確認できるよう、呼び出し元のスキルが提供する適切な登録リンクまたは手順も提示しなければなりません。

printf "Enter CREDENTIAL_NAME (typing hidden): " && read -s val && echo && echo "CREDENTIAL_NAME=$val" >> "ENV_FILE" && echo "Saved."

認証情報が必要なスクリプトの実行

呼び出し元のスキルに含まれるすべてのヘルパースクリプトは、dotenv を使って .env ファイルからこれらの認証情報を自動的に読み込みます。

認証情報を必要とするヘルパースクリプトを呼び出す際に、キーを手動で読み取ったり、シェル環境にエクスポートしたり、CLI 引数として渡したりする必要はありません。上記の安全なプロトコルに従って、キーが .env にあることを確認できたら、スクリプトをそのまま実行してください。スクリプトが認証情報を自動的に読み込みます。