build-raycast-script-command

Raycast スクリプトコマンドの作成

Raycast がスクリプトディレクトリから検出する、# @raycast.* メタデータヘッダー付きの単一の .sh または .py ファイルである、Raycast スクリプトコマンドを作成または修正します。このスキルの対象はスクリプトコマンドのみです。Raycast Extensions API（@raycast/api、ray build、React の <List>／<Detail> ビュー）は対象外です。

使用するタイミング

斜体のトリガーはいずれか1つに一致すれば対象です：

• 新しい .sh または .py の Raycast スクリプトコマンドをゼロから作成する
• 既存の Python またはシェルスクリプトを Raycast スクリプトコマンドに変換する
• # @raycast.title／# @raycast.mode／# @raycast.argument* のメタデータブロックを追加、削除、または修正する
• fullOutput、compact、silent、inline の各モードから選択する（または refreshTime／packageName を修正する）
• # @raycast.argument* の型付き引数を sys.argv[1..3] または $1..$3 に接続する
• スクリプトが Raycast に表示されない理由を診断する（検出、shebang、chmod +x、schemaVersion）
• 標準出力の形式、更新間隔、失敗時の終了コード、依存関係不足時の UX を修正する
• Raycast コミュニティリポジトリの規約に合わせてコマンドを強化する

このスキルを使用しないでください：

• Raycast Extensions（@raycast/api をインポートするもの、ray build／ray develop を使うもの、JSX ビュー、または拡張機能の package.json を含むもの）。このスキルの対象はスクリプトコマンドのみです。
• Chrome 拡張機能またはブラウザー拡張機能の作成。build-chrome-extension を使用してください。
• # @raycast.* ヘッダーがなく、Raycast との連携を意図していない通常の Python／Bash スクリプト。
• ブラウザー自動化のフロー（run-agent-browser）。

import { ... } from "@raycast/api" または "raycast": { ... } を宣言する package.json が見つかった場合、それは拡張機能です。このスキルを終了してください。

トリガーの判定条件

次のすべてに該当する場合に限り、ファイルを対象とします。

1. ファイル名が .sh または .py で終わる（他のインタープリターも使用できますが、まれです）。
2. 1行目がshebang（#!/bin/bash、#!/usr/bin/env python3 など）である。
3. ヘッダーに # @raycast.schemaVersion 1、# @raycast.title …、# @raycast.mode … が含まれ、それらがshebangの直後にある。
4. ファイルが Raycast のスクリプトディレクトリ（Raycast Settings → Extensions → Script Commands → Add Script Directory から追加）に置かれる想定であり、拡張機能の src/ ツリー内には置かれない。

(1)～(4)のいずれかに該当しない、または条件に反する場合は、編集を中止し、対象範囲を確認してください。

重要なルール

ファイルに手を加える前に、以下を読んでください。詳細は references/ にあります。以下のルールには必ず従ってください。

必須メタデータ（すべてのコマンド）

フィールド	必須	備考
# @raycast.schemaVersion 1	はい	固定値です。誤りまたは欠落があると、コマンドは表示されません。
# @raycast.title <Human Title>	はい	Raycast のルート検索に表示されます。
# @raycast.mode <fullOutput|compact|silent|inline>	はい	標準出力の仕様を決定します。
# @raycast.icon	いいえ	絵文字またはパスを指定します。見つけやすさが向上します。
# @raycast.packageName	いいえ	Raycast UI にグループ名を表示します。
# @raycast.refreshTime <Ns|Nm|Nh>	inline の場合のみ必須	秒／分／時間を指定します。
# @raycast.argument1..3	いいえ	引数ごとの JSON オブジェクトです。以下を参照してください。

詳細：references/metadata/required-fields.md。

モードと標準出力の仕様

モード	使用する場面	表示される標準出力	失敗時の UX
fullOutput	結果を読む必要がある場合（リスト、レポート、複数行のテキスト）	結果ウィンドウに全文を表示	最終行とゼロ以外の終了コード
compact	アクションの完了を1行で確認する場合（トースト形式）	空でない最後の標準出力行	最終行とゼロ以外の終了コード
silent	UI を表示しない副作用のみの処理	成功時は何も表示しない	最終行とゼロ以外の終了コード
inline	タイマーで更新されるダッシュボードウィジェット	空でない最初の行。refreshTime ごとに更新	最初の行とゼロ以外の終了コード

inline には # @raycast.refreshTime が必須です。他のモードでは使用しません。

詳細：references/metadata/mode-selection.md、references/metadata/inline-refresh-and-errors.md。

型付き引数（スクリプトコマンドでサポートされるのは3種類のみ）

# @raycast.argument1 { "type": "text",     "placeholder": "query" }
# @raycast.argument2 { "type": "password", "placeholder": "secret", "optional": true }
# @raycast.argument3 { "type": "dropdown", "placeholder": "env", "data": [{"title":"Prod","value":"prod"}] }

• サポートされる型： text、password、dropdown。select、file、number はサポートされません。これらは拡張機能専用です。
• 引数は最大 3 個です。引数2と3は省略可能ですが、引数1は実質的に必須です（Raycast が入力を求めます）。
• Python では sys.argv[1]、sys.argv[2]、sys.argv[3] で読み取ります（省略可能な引数については、必ず長さを確認してください）。
• Bash では "$1"、"$2"、"$3" で読み取ります（必ず引用符で囲み、省略可能な引数については -z で確認してください）。

詳細：references/metadata/typed-arguments.md。

検出に関する必須条件

以下の条件をすべて満たさない限り、コマンドは Raycast に表示されません。

1. スクリプトの親ディレクトリが Raycast Settings → Script Commands に登録されている。
2. ファイルに実行権限がある（chmod +x file.sh / chmod +x file.py）。
3. 1行目が、ユーザーの PATH 上に存在するインタープリターを指定した有効な shebang である。
4. メタデータヘッダーが shebang の直下にあり、その間に空行がない（Raycast は厳密です）。
5. schemaVersion、title、mode がすべて存在し、正しく解析できる。
6. ファイル名に .template. が含まれていない（ユーザーによる編集が必要なため、意図的に非表示になります）。

詳細：references/troubleshooting/discovery-checklist.md。

エラーと依存関係に関する UX

• エラーが発生した場合は、必ずゼロ以外の終了コードで終了します。失敗時、Raycast は stdout/stderr の最後の行（inline の場合は最初の行）を表示します。
• コマンドに jq、gh、requests などが必要な場合は、先に依存関係の不足を検出して、1行のインストール案内を表示してから、ゼロ以外の終了コードで終了します。内容のわからない command not found をユーザーに表示してはいけません。
• compact、silent、inline では、いずれも stdout が集約されるため、複数行にわたる進捗メッセージを出力しないでください。

詳細：references/troubleshooting/runtime-and-output-issues.md、references/foundations/dependencies-and-portability.md。

ワークフロー

ステップ1 — 対象範囲を確認する

何かを書く前に、ワークスペースを調べます。

• 変換する既存の .py または .sh ファイルがあるか、それとも新規作成か。
• 既存のヘッダーに # @raycast.* が使われているか。適切な形式か。
• 周囲のリポジトリが Raycast Extension か（@raycast/api、ray build、"raycast" キーを含む package.json があるかを確認）。該当する場合は、このスキルを終了します。
• Python と Bash のどちらを使うか決めます。references/foundations/language-selection.md と、以下の デフォルト設定 を参照してください。

調査してもタスクの種類が明確でない場合は、references/foundations/scope-and-fit.md を読んでください。

Step 2 — タスクに応じて参照先を選ぶ

作成に着手する前に、該当する分岐の参照資料だけを読みます。

タスク	まず読む資料
新しい Python コマンド	references/foundations/workflow.md → references/python/file-anatomy.md → references/python/implementation-patterns.md → references/metadata/mode-selection.md → references/python/python-recipes.md
新しい Bash コマンド	references/foundations/workflow.md → references/bash/bash-script-patterns.md → references/metadata/mode-selection.md → references/bash/bash-recipes.md
既存のスクリプトを変換する	references/foundations/workflow.md → references/metadata/required-fields.md → references/foundations/dependencies-and-portability.md → references/troubleshooting/discovery-checklist.md
モードを選択／修正する	references/metadata/mode-selection.md → references/metadata/inline-refresh-and-errors.md → references/troubleshooting/runtime-and-output-issues.md
引数を追加／修正する	references/metadata/typed-arguments.md → references/python/implementation-patterns.md または references/bash/bash-script-patterns.md
コマンドが表示されない	references/troubleshooting/discovery-checklist.md → references/metadata/required-fields.md
ランタイム／出力が誤っている	references/troubleshooting/runtime-and-output-issues.md → references/metadata/mode-selection.md → references/metadata/inline-refresh-and-errors.md
Python と Bash のどちらを使うか決める	references/foundations/language-selection.md
共有可能にする	references/foundations/community-repo-conventions.md → references/foundations/dependencies-and-portability.md
出典／ソース監査	references/foundations/source-map.md

Step 3 — 作成または修正する

• assets/templates/python-script-command.py または assets/templates/bash-script-command.sh をひな形として使います。これらは完成コードではなく、ベースとなるファイルです。
• メタデータブロックはシバンの直下に置きます。Python と Bash の両方で # @raycast.* を使います（# の行コメント構文は同じです）。
• 引数は慎重に読み取ります。Python では sys.argv の長さを確認し、Bash では "$1" を引用符で囲み、-z "$2" を確認します。
• 外部ツールごとに、依存関係が不足していないか事前に確認し、ユーザーが読める1行のエラーメッセージを追加します。
• 選択したモードの stdout の仕様に正確に合わせます。上の表を参照してください。

Step 4 — 検証する

同梱のチェッカーを、実際のコマンドファイルに対して実行します。

1. scripts/check-raycast-script-metadata.sh path/to/command.{py,sh} — シバン、必須メタデータ、モードの妥当性、inline における refreshTime の有無、型付き引数の JSON を検証します。
2. scripts/preview-script.sh path/to/command.{py,sh} [args...] — コマンドを実行し、宣言されたモードで Raycast が stdout をどのように表示するかをプレビューします。
3. コマンドが見つからない場合は、references/troubleshooting/discovery-checklist.md に従います。
4. 出力／更新／終了の動作に問題がある場合は、references/troubleshooting/runtime-and-output-issues.md に従います。
5. 到達した検証段階を正確に報告します（read / metadata-checker / preview / installed-and-ran-in-Raycast）。「問題なさそう」という印象だけをスモークテストとして扱わないでください。

デフォルト（タスクで指定がない限り使用）

• Python：HTTP／API 呼び出し、JSON の解析、複雑なテキスト処理、構造化データを扱う複数ステップの処理。
• Bash：既存の CLI（gh、pbcopy、osascript、open）を使う薄いラッパー、小規模なファイルシステム操作。
• モード fullOutput：ユーザーに結果を読んでもらう場合。
• モード compact：「処理しました」という1行の確認メッセージを表示する場合。
• モード silent：有用な出力を伴わない副作用のみの場合（クリップボードへのコピー、アプリの起動、システム操作）。
• モード inline：ダッシュボード形式のステータスウィジェット（バッテリー、天気、ビルド）に限り使用し、refreshTime を設定します。

同梱スクリプト

各スクリプトの隣には、対応する .md ドキュメントがあります。

スクリプト	目的	変更を加えるか
scripts/check-raycast-script-metadata.sh	shebang、必須メタデータ、モード、インラインの refreshTime、型付き引数の JSON を検証します。scripts/check-raycast-script-metadata.md を参照してください。	いいえ
scripts/preview-script.sh	コマンドを実行し、宣言されたモードに応じた Raycast の標準出力表示の仕様をプレビューします。scripts/preview-script.md を参照してください。	いいえ

同梱アセット

アセット	目的
assets/templates/python-script-command.py	メタデータヘッダー、引数のひな形、依存関係の確認、終了コードの適切な処理を含む Python コマンドのひな形です。
assets/templates/bash-script-command.sh	同じひな形を含む Bash コマンドのひな形です。

リファレンス一覧

ファイル	読むタイミング
references/foundations/scope-and-fit.md	タスクが完全な Raycast 拡張機能ではなく、本当に Script Command に適しているか判断するとき。
references/foundations/workflow.md	コマンドを作成または変換するための、最初から最後までの構築手順。
references/foundations/language-selection.md	Python と Bash のどちらを選ぶか判断するとき。
references/foundations/community-repo-conventions.md	共有にあたり、raycast/script-commands リポジトリの規約に合わせるとき。
references/foundations/dependencies-and-portability.md	外部ツールやパッケージに依存するコマンド、または移植性を維持する必要があるコマンド。
references/foundations/source-map.md	内部リファレンスの出典情報、および Raycast のオリジナル調査に基づいてスキルを拡張するとき。
references/metadata/required-fields.md	メタデータヘッダーを追加または修正するとき。
references/metadata/mode-selection.md	fullOutput、compact、silent、inline から選ぶとき。
references/metadata/inline-refresh-and-errors.md	インラインの更新間隔、1 行目／最終行の動作、失敗時のセマンティクス。
references/metadata/typed-arguments.md	@raycast.argument* を追加、変更、またはデバッグするとき。
references/python/file-anatomy.md	Python コマンドファイルの構成：shebang、ヘッダー、コード領域。
references/python/implementation-patterns.md	sys.argv の接続、依存関係に関する注記、エラーメッセージ、出力パターン。
references/python/python-recipes.md	コピーして形を整えられる、具体的な Python コマンドのパターン。
references/bash/bash-script-patterns.md	Bash ベースの Script Command を作成または修正するとき。
references/bash/bash-recipes.md	コピーして形を整えられる、具体的な Bash コマンドのパターン。
references/troubleshooting/discovery-checklist.md	コマンドが Raycast に表示されないとき。
references/troubleshooting/runtime-and-output-issues.md	出力、更新、または失敗時の動作に問題があるとき。

ガードレール

• 上の表にないメタデータフィールドを作り出さないでください。Raycast が提供する情報で確認済みのフィールドのみ有効です。
• @raycast/api、AI Extension、拡張機能の Form スキーマをインポートしないでください。これらは Script Command ではなく拡張機能に属します。
• サポートされていない引数の型（select、file、number）を使用しないでください。使用できるのは text、password、dropdown のみです。
• refreshTime を設定せずに inline を宣言しないでください。
• compact、silent、inline では、複数行の進捗情報を出力しないでください。
• オプション引数を安全でない方法で読み取らないでください。sys.argv の長さを確認し、"$1"／"$2"／"$3" を引用符で囲んでください。
• command not found がユーザーに表示されないようにしてください。依存関係を事前に確認し、わかりやすいエラーメッセージを出してください。
• コマンドの初回使用前にユーザーによる編集が意図されている場合を除き、最終ファイル名に .template. を残さないでください。
• 対応するリファレンスがある場合、シェルや Python のチュートリアル内容で水増ししないでください。

出力契約

タスクが完了したら、次の内容を報告してください。

• コマンドファイルのパス
• 選択したモードと、そのモードが出力形式に合致する理由
• 存在するメタデータフィールド（追加した任意項目があればその項目も）
• サポートする引数と、$1..$3 / sys.argv[1..3] への対応
• 依存関係とセットアップに関する注意事項
• 実施した検証：metadata-checker の結果とプレビューの結果
• Raycast のインストール／使用方法（該当する場合はスクリプトディレクトリの追加方法を含む）
• 到達した検証段階（read / metadata-checker / preview / installed-and-ran-in-Raycast）