cawcut-app-run

Name: cawcut-app-run
Author: cawcut

github.com/cawcutクリエイティブ・メディア2277 回インストール1 日前に更新

リポジトリ

cawcut-app-run について

CawCut Apps の検索、閲覧、実行を行うスキルです。CawCut CLI で最新カタログを確認し、App の入力を集め、該当する App がない場合は cawcut-generate に引き継ぎます。

主な機能

01最新 App カタログの閲覧
02App の機能と入力項目の確認
03CLI から選択した App を実行
04該当なしの依頼を cawcut-generate に引き継ぎ

活用シーン

01クリエイティブな依頼に合う App の検索
02実行前の App 機能の確認
03入力を集めて App を実行

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/cawcut/skill --skill cawcut-app-run

インストール後、Claude Code で/cawcut-app-runを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/

app-inputs.md

app-presentation.md

intent-matching.md

troubleshooting.md

詳細

CawCut App の実行

CawCut-App に関連するすべての操作のエントリーポイントです。機能の確認（「このアプリで何ができますか」「どのアプリが利用できますか」）、カタログの閲覧、アプリの実行に対応します。cawcut app list、cawcut app describe、cawcut app run をラップします。また、リクエストに一致するアプリがない場合の判断を行い、cawcut-generate に引き継ぎます。

スキルファイルは英語のみです。 SKILL.md と references/ に、中国語やその他の英語以外の文章を含めてはいけません（YAML の description に含まれるトリガーフレーズも対象です）。ユーザーの言語に合わせるのは、ライブ応答の reply_language のみです。

Step -1 — 引き継ぎ状態（最初に確認）

このターンが、cawcut-generate によるアプリカタログの確認後、ユーザーが特定のアプリを使いたいと確認したこと（「Check the App catalog first」ルールを参照）をきっかけに始まった場合、そのアプリはすでに決定済みです。Step 1 のカタログスコアリングとアプリ選択メニューは省略してください。cawcut app describe "<app name>" を実行し、テーブルと入力メニューに進んでください。

必要に応じて、引き続き最新情報を取得してください： cawcut app run の前に、このターン内で cawcut app list --json を新たに実行し、内部アプリ ID を特定してください。以前のメッセージや、同じターン内で cawcut-generate が以前実行したコマンドのカタログ JSON は使わず、そのコマンドの出力だけを使用してください。describe は常に最新情報を取得してください。会話の記憶にある過去の describe のスナップショットで代用してはいけません。

この引き継ぎ後にユーザーの対象や目的が変わった場合（ツール呼び出しが拒否または中断された後も含む）、Step -1 は適用されなくなります。Step 1 からやり直し、カタログを再スコアリングしてください。

それ以外の場合は、Step 0 に進んでください。

Step 0 — 初期化

実行環境に応じてログインモードを選択

コマンドが実際に実行される場所に基づいて選択してください。ユーザー自身のコンピューターで実行する場合は、cawcut auth login --browser --json を実行します。CLI がブラウザーを開き、承認を待ちます。リモート環境、VM、またはユーザーのブラウザーにアクセスできないコンテナーで実行する場合は、cawcut auth login --device-auth --json を実行し、authorization_url をユーザーに送って、ユーザー自身のコンピューターで開いて承認してもらいます。どちらのモードも JSON に対応しています。構造化出力が必要だからといって、デバイス認証を選ぶ必要はありません。エージェントの名前、非 TTY シェル、localhost URL だけでは、コマンドの実行場所は判断できません。既知の実行コンテキストと明示的なモードフラグを使って、CLI の自動判定を上書きしてください。

デバイスログインの場合は、続けて cawcut auth login --complete --wait --timeout 60 --json を実行してください。ツールの実行タイムアウトが短い場合は、next_poll_after_seconds に従って、--complete --json の呼び出しを個別に行ってください。デバイスログインが中断された場合や wait_timeout が返された場合は、新しいリンクを作成せず、保存済みの現在のリクエストを再開してください。ブラウザーログインでは従来のループバックコールバックを使用します。中断された場合は、--complete を使わず、cawcut auth login --browser --json を再度実行してください。status=pending は認証成功を意味しません。元の操作を再試行するのは、status=authenticated の場合のみです。拒否または期限切れになった場合は、このリクエストを終了してください。承認リンクを際限なく自動作成してはいけません。パスワード、トークン、またはウェブページからコピーしたコードをユーザーに尋ねてはいけません。

初期化は、ユーザー向けのフェーズとしてではなく、サイレントな安全策として実行してください。

AI セッションあたり最大 1 回です。 この AI セッションで cawcut コマンドがすでに成功している場合は、すべてのブートストラップチェックをスキップして続行します。
明示的なチェックコマンドは 1 つだけ使用します： cawcut upgrade check --json。
- cawcut --version、command -v cawcut、cawcut auth status も実行してはいけません。
- "update_available": true の場合は、Bash 経由で自分で cawcut upgrade を実行します（ユーザーに入力を求めてはいけません）。CLI とスキルが更新されます。成功したら、Step 1 からこのスキルを続行します。停止したり、ユーザーに再度実行するよう求めたりしてはいけません。
- "ahead_of_registry": true の場合は、アップグレードせずに続行します。ダウングレードや cawcut upgrade の実行をユーザーに求めてはいけません。
- cawcut が見つからずチェックに失敗した場合は、npm 経由で CLI をインストールするようユーザーに求めます（外部ユーザーの場合は、git clone やリポジトリの ./setup は使用しません）。
```
npm install -g @ubnt/cawcut
```
  インストールが成功したら、ブートストラップを続行します。認証は以下の手順 4 で行います。
- その他のチェック失敗については続行し、後続の CLI コマンドが失敗した場合に限り警告に言及します。
ブートストラップ後に「bootstrap checks passed」と出力したり、「何を実行しますか？」と尋ねたりしてはいけません。すぐ下の「アプリの検出」に進みます。
最初の実際のコマンド（cawcut app list --schema、cawcut app describe、または cawcut app run）で認証を検証します。トークン／認証エラー（Token expired を含みます）で失敗した場合は、上記のログイン手順に従います。実行環境に適したモードを使用し、status=authenticated になった後に限り、失敗したコマンドを 1 回だけ再試行します。CLI コマンドは自分で実行し、ユーザーが行うのはブラウザーでの承認のみです。
このスキルの参照ファイル（references/troubleshooting.md、references/app-inputs.md、references/intent-matching.md、references/app-presentation.md）は、スキル本文の先頭に表示されているベースディレクトリにあります。Read で <base_dir>/references/<file>.md を直接読み込んでください。参照ファイルを探すために find／grep を使ってはいけません。ベースディレクトリはシンボリックリンクの場合があり、通常の find <dir> ではリンク先がたどられず、見つからないことがあるためです。
構造化されたユーザー選択ツール（毎セッション確認）。 Claude Code では、選択肢から選ぶ場面すべてで AskUserQuestion を使用します。Cursor では AskQuestion を使用します。いずれかのツールが許可ツールの一覧にある場合は、このスキル内の列挙形式の判断すべて（アプリの選択、同名項目の選択、列挙値／デフォルトの分岐、メディアソース、任意入力のスキップ／指定、アップロードの復旧）で必ず使用します。ただし、選択肢が多すぎて収まらない場合に限り、その選択の一括分については番号付きテキスト表を使用できます（「対話型選択」を参照）。AskUserQuestion／AskQuestion が使用可能で選択肢の数が収まる場合、番号付きのテキストメニューをデフォルトで使用してはいけません。ユーザーがこのツールの呼び出しを一度断った場合でも、次の判断で使うのをやめてはいけません。拒否メッセージの読み取り方については、「対話型選択」の冒頭のルールを参照してください。

カタログの最新性（必須）

信頼できる情報源： 現在の目的に関して、このユーザーメッセージのターン内で実行した cawcut app list … コマンドの出力のみです。以前のメッセージに出てきたアプリ名、ID、件数、JSONを、信頼できる情報として扱わないでください。会話の記憶はカタログではありません。以前のユーザーメッセージでの「一致する App なし」という結論を再利用してはいけません。

ユーザーメッセージごとのルール（最優先）： 新しいユーザーメッセージを受け取るたびに、返信の作成や他のツールの呼び出しより先に、必ず cawcut app list --json を実行してください。これは機械的な手順であり、判断の余地はありません。メッセージがアプリの発見、一致判定、閲覧、cawcut app run、cawcut-generate へのルーティングに「関係する可能性があるか」を考える前に実行してください。前回のメッセージ以降、サーバー上でカタログが変更されている可能性があります（例：ユーザーがウェブ上で新しい App を公開した場合）。

次のいずれかに該当する場合も、ステップ 1 を再実行してください：

ユーザーのツール呼び出し（AskUserQuestion／AskQuestion／メニュー）が拒否または中断され、次のメッセージで件名、目的、対象の App が変わった場合。入力収集中の途中を含め、同じやり取りの「フォローアップ」であっても、新しいユーザーメッセージと同様に扱い、ステップ 1 からやり直してください
発見、閲覧、「どんなアプリがあるか」という質問、またはカタログの先回りした提示を行う場合（上記のユーザーメッセージごとのルールで対応済みの場合を除く）
現在の目的に対して、意図のスコアリングやアプリ選択メニューが必要な場合
ユーザーが名前で選択した App の ID を解決する場合（このターン中に cawcut app list --json を新たに実行してください）
「App が見つからない」場合の復旧
ユーザーがアカウントを切り替えた、再ログインした、または cawcut auth login が成功した場合
ユーザーが新しい App を公開、共有、作成したと伝えた場合
ユーザーが App の更新または再一覧表示を求めた場合
以前の一覧表示が絞り込まれていた場合（例：Official のみ）、その後ユーザーが My Apps または Shared Apps を求めた場合
app describe／app run が見つからないエラーまたはアクセスエラーを返した場合

ステップ 1 のカタログスコアリングを省略できるのは、以下のすべてを満たす場合に限ります（同じユーザーメッセージのターン内で、件名と目的も同じ場合）：

このユーザーメッセージに対して cawcut app list --json をすでに実行し、カタログのスコアリングを完了しているか、一致する App がないことを確認している
このユーザーメッセージ内で、現在の件名と目的に使用する App がすでに決定している（ユーザーによる選択、この目的に対する強い自動マッチ（70% 以上）、または cawcut-generate からこの App 名へのステップ -1 の引き継ぎ）
その名前の App のみに対して describe と入力の収集を進める場合、または run の前にこのターンで cawcut app list --json を新たに実行して ID を解決する場合
新しいユーザーメッセージがないのに、アプリ選択メニューを再度表示しない
このユーザーメッセージ内で、ユーザーの件名と目的が変わっていない（ツール呼び出しが拒否または中断された後も含む）

ユーザーメッセージをまたいで、ユーザーメッセージごとの app list を省略してはいけません。件名、機能、表現がまったく同じ場合も同様です。

必須ゲート： ワークフロー §3（入力を指定して実行）では、cawcut app run の直前にプリフライトチェックを実行します。詳細はそちらを参照してください。

ステップ 1 — 意図の振り分け（カタログを取得する前）

引き継ぎ以外の呼び出しは、すべてここから始めます。以下のカタログスコアリングに進む前に、上記の Catalog freshness にある Per-user-message rule と Skip Step 1 のチェックリストを適用してください。このユーザーメッセージに対して cawcut app list --json をまだ実行していない場合は、最新のカタログを取得してスコアを付けてください。前のメッセージの一覧、選択済み App、または「該当なし」という結論を再利用してはいけません。

公式機能への最短経路 — ユーザーの表現から、シンプルな単一ステップの公式生成リクエスト（App 不要）を判別します。

意図される `--capability`	ユーザーが使う可能性のある表現
`text-to-image`	テキストから画像、テキストから画像を生成、画像を生成、画像を作成
`text-to-video`	テキストから動画、テキストから動画を生成、動画を作成
`image-to-image`	画像から画像、画像から画像を生成、この画像を編集／スタイル変更／リミックス
`image-to-video`	画像から動画、画像を動画に、写真をアニメーション化
`omni-to-video`	omni から動画、omni-to-video

ユーザーメッセージごとに必須の cawcut app list --json を実行して最新カタログを確認した結果、該当しそうな App がなく、リクエストがこれらの機能を明示または暗示し、テンプレート／キャンペーン／マーケットプレイス／複数入力／App 名の手がかりを含まない場合は、暗示された --capability を指定して cawcut-generate に直接引き継ぎます。それ以外（曖昧な場合、またはブランド／テンプレート／複数ステップのワークフローが示唆される場合）は、以下のカタログスコアリングに進んでください。

検索か実行か — ユーザーが App の機能、生成するもの、必要な入力について尋ねている場合、またはカタログを見たい場合は、intent = discovery に設定します（references/app-presentation.md を参照）。ユーザーが実行を確認するまでは、実行リクエストとして扱わないでください。

カタログスコアリング — その他の場合はすべて、最新のカタログを取得し（以下のステップを参照）、references/intent-matching.md の基準を適用してください。

結果	対応
検索の意図	`references/app-presentation.md` に従って提示し、ユーザーが実行を求めない限り終了
強い一致（スコア ≥ 70）	選択済みとして扱う — `describe` ＋表＋入力メニュー
弱い一致／同点（40～69、または上位 2 件の差が 15 点以内）	必ず `AskUserQuestion` / `AskQuestion` を使い、上位 2～4 件の App ＋「代わりに公式生成」を提示する。番号付きテキストを使うのは、ツールが利用できない場合、または表示量の制限が適用される場合のみ
該当なし（すべて 40 未満、カタログが空）	該当する場合は、暗示された `--capability` を指定して `cawcut-generate` に引き継ぐ

cawcut-generate に引き継いだら、このターンはそこで終了としてください。同じターン内でカタログを再確認してはいけません。新しいユーザーメッセージ（新しいターン）では、話題が関連しているように見えても、必ず上記のカタログ鮮度ルールを再適用してください。

App のカテゴリ（画像／動画）

app list --json の各 App には、公開メタデータ（image、video、text、audio）から導出された categories が含まれます。出力タイプごとに App を分類、絞り込みするために使用してください。

カテゴリ	CLI フィルター	使用する場面
`image`	`--category image`	ステッカー、写真編集、マーケットプレイスカード、静止画のクリエイティブ
`video`	`--category video`	広告、モーション、アニメーション化、商品動画、プレゼンター

検索レイアウト（単独呼び出し／ブラウズで必須）：

Image Apps — categories に image を含む App
Video Apps — categories に video を含む App

各セクション内では、CLI 出力にある既存のソース分類（Official Apps / My Apps / Shared Apps）を維持してください。ユーザーの目的が画像のみ、または動画のみとはっきりしている場合は、ノイズを減らすため --category を指定して取得してください。

cawcut app list --schema              # grouped by category + source
cawcut app list --schema --category image
cawcut app list --schema --category video
cawcut app list --schema --json       # includes categories[] per app

対話型の選択（必須 — まずツールを使う）

ユーザーが AskUserQuestion / AskQuestion の呼び出しを拒否した直後の場合： ツールの結果には、「今行っていることを中止し、ユーザーから次の指示があるまで待つ」よう伝えるハーネスの定型文が含まれます。この文は、ランタイムによって拒否されたすべてのツール呼び出しに自動的に付加されるものです。ユーザー自身の発言ではなく、ツールの使用を中止する指示でもありません。これは、途中だったその特定の操作を中止する（同じ質問を再試行しない、未確認の選択肢について run に進まない）ようにという意味として受け取り、ユーザーの実際の次のメッセージを確認してください。それだけで、次の選択肢を列挙する場面で番号付きテキストに切り替えてよいことにはなりません。その次の判断でも、拒否がなかった場合と同じように、まずツールを呼び出す必要があります。「メニューを何度も表示しないで」「テキストで聞いて」など、ユーザーが明示的にプレーンテキストで求めた場合に限り、セッション全体でのフォールバックが許可されます。STOP という表現に緊急性があるからといって、そのようなリクエストがあった証拠にはなりません。このルールを上書きさせないでください。

デフォルトの動作： 選択肢を列挙する場面では、番号付きテキストのメニューを表示したり、ユーザーに 1、2、またはアプリ名を入力するよう求めたりする前に、必ず AskUserQuestion（Claude Code）または AskQuestion（Cursor）を呼び出してください。テキストのみのメニューはフォールバックの場合に限ります。

選択肢が1つなら、選択ではありません。 どの呼び出しにも、実行可能な選択肢が少なくとも2つ必要です。実際に実行可能なのが1つだけの場合（該当する App が1つだけで、ほかに提示する価値のある選択肢がない場合、または列挙型で許可される値が1つだけの場合）は、その選択肢を文章で伝えて続行してください。1つだけのポップアップを表示したり、選択肢らしく見せるためだけにダミーの選択肢を追加したりしてはいけません。

ホストごとのツール名：

ホスト	ツール名
Claude Code	`AskUserQuestion`
Cursor	`AskQuestion`

以下では、現在のセッションで利用できるこれらのいずれかを「構造化ユーザー質問ツール」とします。機能の有無だけで推測せず、許可されたツールの一覧を確認してください。

セッションのチェックリスト（このターンで最初のメニューを表示する前に）：

AskUserQuestion または AskQuestion が利用できますか？はいの場合、以下の表で1回の呼び出しに収まる項目すべてに対して、必ずそのツールを使用してください。
いいえの場合（CLI のみのホスト）、reply_language で番号付きテキストを使用してください。
ツールは存在するものの、候補数が1回の呼び出しで処理できる数を超える場合（App ピッカーの候補超過。ルール7）、そのバッチに限り番号付きのテキスト表を使用してください。その後、次の少数の選択では AskUserQuestion / AskQuestion の使用を再開してください。

ツールが利用可能な場合は禁止： 番号付きテキストメニュー（1. … 2. …）、「番号または名前で返信してください」という指示、またはアプリ名、入力キー、列挙値をユーザーが記憶から入力するよう求めること。

手順	構造化ユーザー質問ツールを必ず使用する場面
App ピッカー	`app list --schema` に含まれるすべてのアプリ（ラベル＝名前＋クレジット＋短い説明。アプリ ID は含めない）。候補数がツールの処理上限を超える場合は、App ピッカーの候補超過（ルール7）を参照してください。
重複する名前	一致する各項目（ラベル＝説明＋ソース。アプリ ID は含めない）
列挙型／デフォルトテキスト	各許可値、および該当する場合は「デフォルトを使用」／「カスタム」
メディア入力	`Photo already in chat` / `Paste HTTPS URL` / `Local file path`
任意入力	`Skip` / `Provide`

構造化ユーザー質問ツールのルール：

選択肢を列挙できる場合は、自由入力の返信を待つ前に必ず呼び出します。
可能な限り、1 つのフォームにつき 1 つの判断にします（例：pick-app、次に scene-photo-source）。
label はユーザーに表示する内容です。id は短く、安定した値にします（photo-sticker、3d-model-zh、3d-model-en）。
ラベルにアプリ ID を入れてはいけません。ユーザーが選択した後、このターンで新たに cawcut app list --json を実行し、その出力だけから ID を特定します。
ユーザーが Custom ／ Local file path ／ Paste URL を選んだ場合に限り、その内容（テキストまたはパス）を尋ねるフォローアップを 1 つ行います。それでも入力 KEY 名を入力するよう求めてはいけません。
フォールバックのみ： AskUserQuestion ／ AskQuestion が利用できない場合、またはそのバッチでツールがサポートする選択肢の数や構造を超える場合に限り、reply_language の番号付きテキストメニューを使います。ある判断でフォールバックしても、次の少数の選択肢による判断が免除されるわけではありません。条件に合う場合は再確認し、再びツールを使います。UX ルール 11 の統合テキストブロックはフォールバック時のみの形式であり、ツールが利用できる場合の標準形式ではありません。
アプリ選択肢の超過： ツールで扱える選択肢は通常、1 つの質問につき約 2～4 個、1 回の呼び出しにつき約 4 つの質問までです。app list --schema の候補がこの数を超える場合は、候補を番号付きテキストテーブルで表示して選べるようにします。先頭の # 列に番号を置き、続けて名前、ソース、クレジット、説明を表示し、番号またはアプリ名のどちらでも返信できることを伝えます。このテキストによるフォールバックは、その数を超える候補一覧にのみ適用されます。ユーザーが候補を絞り込んで特定の App を選んだ後は、重複コピーの選択、列挙値、メディアソース、オプション入力を省略するか提供するかといった、その後の少数選択肢による判断では、再び AskUserQuestion ／ AskQuestion を必ず使います。これは cawcut-generate の Phase A Choice 2 におけるモデル一覧の超過、および Phase B の軸のバッチ処理（コストや視覚的影響のある軸が 4 個を超える場合のルール）と同じ方式です。

UX ルール

選択優先 — ユーザーがアプリ名を指定していない場合は、まず cawcut app list --schema を実行し、候補数が収まる場合は、必ずアプリ選択のために AskUserQuestion / AskQuestion を呼び出します（番号付きテキストは、アプリ選択肢が多すぎる場合のみ使用。ルール 7）。アプリ ID は表示しないでください — 名前、ソース、クレジット、説明、入力の概要のみを使用します。
テンプレート優先 — ステップ 1（意図のトリアージ）を適用します。references/intent-matching.md に従って現在のカタログを評価し、まず有力な候補を提案します。cawcut-generate へのフォールバックは、ステップ 1 の結果（該当なし、カタログが空、または公式機能で明らかに対応できる場合）に限ります。
選択時にアプリ情報を開示（必須） — ユーザーによる選択、自然言語の依頼からの自動マッチング、または単一のおすすめなど、アプリを選択した場合は必ず、入力を尋ねる前に次の操作を行います。
1. cawcut app describe "<app name>" を実行します（必要に応じて先に候補を区別します）。
2. reply_language でアプリのメタデータ表と入力表を提示します（「アプリの入力をユーザーに提示する」を参照）。
3. 本文ではアプリ名と説明を最初に示します。アプリ名を挙げずに「このアプリ」とだけ言うのは禁止です。
4. 続けて入力収集メニューを表示します（UX ルール 11～12）。 禁止事項： 名前、ソース、機能、入力概要のいずれも示さず、「このアプリが役立ちます」のような曖昧な説明をすること。どのアプリか、何が必要かを説明せずに「動画のパスを入力してください」とすぐに尋ねること。
自然言語の依頼も受け付けます — references/intent-matching.md のステップ 1 にある評価基準を使い、アプリ名、説明、ソース、クレジット、公開されている入力要件に照らして、ユーザーの目的に合うアプリを提案します。あるアプリのスコアが 70 以上の場合は選択済みとして扱い、すぐに describe を実行してアプリの詳細をすべて開示します。ユーザーが「どのアプリ？」と尋ねるのを待たないでください。
返信言語：
- スキルを単独で呼び出した場合 → 英語。 ユーザーが実質的なテキストを添えずにスキルコマンドのみを実行した場合（例：/cawcut-app-run、cawcut-app-run、またはスキル名のみ）は、メニュー、概要、質問に使用する reply_language を英語に設定します。
- 以降は会話に合わせます。 ユーザーが別の言語で具体的な依頼や追加質問をしたら、その言語に reply_language を切り替え、セッションの残りの間はその言語を使用します（ユーザーが明示的に英語を求めた場合を除く）。
- すべての説明文、状況の概要、選択肢のラベル、質問、問題解決の案内には reply_language を使用します。
- CLI コマンド／フラグ、モデル ID、入力キー、JSON キー、URL、生のエラーコードは英語のままにします。アプリ ID は内部情報です — 必要な場合は、このターン中に新たに cawcut app list --json を実行して ID を解決します。ユーザー向けのアプリ一覧に ID を表示しないでください。
- CLI の生の英語出力をそのままユーザー向けの回答に貼り付けず、reply_language で要約します。
積極的に候補を提示 — ブートストラップ後は、ユーザーから一覧を求められるのを待たないでください。アプリ名が指定されていない場合は、すぐに cawcut app list --schema を実行し、アプリ ID を含めず、アプリを画像アプリと動画アプリに分けて要約し、アプリを選ぶか目的を自由に説明するようユーザーに尋ねます。
実行前に必ず入力を確認 — 先に cawcut app describe "<app name>" を呼び出します（または --json の結果から解決する場合は cawcut app describe <app_id>）。
実行前に同名アプリを区別 — 名前が複数のアプリに一致する場合、候補数が収まるなら、必ずコピーごとに 1 つの選択肢を用意した AskUserQuestion / AskQuestion を呼び出します（ラベルには説明、ソース、入力の概要を含めます）。実行前にクリックまたは選択を待ちます。番号付きテキストによる CLI フォールバックは、ツールを利用できない場合に限ります：cawcut app run "<name>" --pick <n>。
固定値や選択可能な値はすべて選択式にする — cawcut-generate と同じ基準を適用します。アプリ名、入力キー、列挙値、フラグをユーザーに記憶から入力させないでください。describe の後、フィールドにデフォルト値、options、または少数の既知の値がある場合は、必ず AskUserQuestion / AskQuestion を呼び出します（該当する場合は「デフォルトを使用」も選択肢に含めます）。スキーマ上、デフォルト値のない自由記述であり、かつユーザーがまだ内容を提示していない場合に限り、自由形式の内容を尋ねます。ツールが利用できる場合は、選択肢の少ない決定に番号付きテキストをデフォルトで使わないでください。
範囲の広すぎる入力質問は禁止 — 次のような質問は禁止です。

「実行するアプリは何ですか？」
「必須入力の値を入力してください。」
「Input - Scene Photo の値を貼り付けてください。」代わりに、app list --schema / app describe に基づく具体的な番号付き選択肢を必ず表示します。

実行前に入力収集メニューを表示 — describe の後、実行前に入力の選択肢を収集します。優先順位： ツールが利用できる場合は、必ず AskUserQuestion / AskQuestion の呼び出しに分解します。フィールドが複数ある場合は、「入力の指定方法」の概要（デフォルト値とカスタム値）に関する呼び出しを 1 回行い、その後、判断が必要なフィールドごとに 1 回ずつ呼び出します（メディアソース A/B/C、テキストの定型文かカスタムか、列挙値の一覧）。以下の統合テキストブロックはフォールバック表示専用です。AskUserQuestion / AskQuestion を利用できない場合、またはサブ選択肢の数がツールで扱える上限を超える場合（アプリ選択肢が多すぎる場合、対話型選択のルール 7）に限って使用します。ツールが利用できる場合は、分解した判断事項を 1 つの番号付きテキストメニューにまとめないでください。 フォールバックの例（英語） — AskUserQuestion / AskQuestion が利用できない場合、またはオーバーフローが発生する場合：

Ready to run Photo to Sticker. Choose how to fill inputs:
1. Use defaults only (if any exist) and run — list which fields use defaults
2. Scene photo — pick one:
   A. Use a photo you already shared in this chat (I'll use that file/URL)
   B. Paste an HTTPS image URL
   C. Give a local file path (e.g. ~/Pictures/photo.jpg, or C:\Users\you\Pictures\photo.jpg)
3. Text fields (only when required and no default) — pick a starter or write custom:
   A. Use suggested prompt: "..."
   B. Custom (you describe; one short message)
4. Run now with choices above

AskUserQuestion / AskQuestion が利用可能な場合（必須の方法） — 同じ「写真をステッカーに」シナリオを分解します（1 回の呼び出しにつき 1 つの判断。ラベルは reply_language で指定します）。

シーン写真のソース — 次の選択肢を指定して AskUserQuestion / AskQuestion を使用します。
- Photo already in chat — このチャットですでに共有した写真を使用します
- Paste HTTPS URL — HTTPS 画像 URL を貼り付けます
- Local file path — ローカルファイルパスを指定します（例：~/Pictures/photo.jpg、または C:\Users\you\Pictures\photo.jpg）
テキストフィールド（必須でデフォルト値がない場合）— 次の選択肢を指定して AskUserQuestion / AskQuestion を使用します。
- Use default / Use suggested prompt — デフォルト値または提案された値を表示します
- Custom — その後、ユーザーのテキストについて追加の質問を 1 つ行います（上記のルール 5）入力が存在しない場合は、その入力に関する判断を省略して、実際のスキーマに合わせてください。ユーザーが入力する必要のあるものとして、入力の KEY 名を表示してはいけません。キーは CLI 専用です。

入力の種類ごとに、自由形式のパラメーター入力ではなくメニューを表示します — 必ず、インタラクティブ選択（上記）に従って、各項目の選択肢を AskUserQuestion / AskQuestion で提示してください。以下の番号付きメニューは、テキストで代替する場合の形式にすぎません。

種類	ユーザー向けメニュー（KEY 名は絶対に尋ねない）
`text` + デフォルト値	1) デフォルトを使用（値を表示） 2) カスタムテキスト
`text` + デフォルト値なし	1) アプリの説明から候補を2～3個提案 2) カスタム（ユーザーが内容を一度入力）
`text` + スキーマに列挙型／選択肢あり	`describe --json` にあるすべての選択肢に番号を付けます。スキーマで許可されている場合に限り「その他」を追加します
`image` / `video` / `audio`	1) チャットにあるファイル 2) HTTPS URL 3) ローカルパス — ユーザーは生の `--input` キーではなく、A/B/C を選びます
任意入力	1) スキップ 2) 指定（続けて、その種類のサブメニューを表示）

describe の KEY 列を使って、選択されたメニュー項目を --input key=value に自分でマッピングしてください。ユーザーが選ぶのは選択肢であり、パラメーター名ではありません。
メディア入力では、ユーザーがメニューの分岐を選んだ後、HTTPS URL または @ を先頭に付けたローカルパスを渡します。このファイル内のパスは簡潔さのため POSIX 形式で記載しています。Windows では、同じ入力は --input "key=@C:\Users\you\Pictures\photo.jpg" です。また、~ は CLI によっても、引用符で囲まれた引数内の PowerShell によっても展開されません。ユーザーが指定したパスは、そのままの形式で渡し、スペースを含む場合は引用符で囲みます。一方のプラットフォームの形式を、もう一方の形式に書き換えてはいけません。
説明用のメディア例を実際の入力として使用してはいけません。 image / video / audio 入力では、describe の出力（sample:、x-cawcut-sample-url）、SKILL.md、references/、その他のドキュメントにあるサンプル URL、パス、アセットは、ヒントにすぎず、使用可能なリソースではありません。ユーザーがこの会話でそのファイルまたは URL を明示的に指定していない限り、--input に渡してはいけません。必要なメディアがない場合は、メディアのサブメニュー（ルール12）を表示して待ちます。でっち上げた例やプレースホルダーの例を使って実行してはいけません。また、選択肢を示さずに URL／パスだけを尋ねてはいけません。
長時間かかるジョブの完了まで待機するよう、--wait を渡します。結果の URL はすべて伝えてください。
結果が画像、動画、音声ファイルの場合は、必ず --download を渡します。CLI がプラットフォームに適したダウンロードフォルダー（macOS/Linux では ~/Downloads、Windows では %USERPROFILE%\Downloads）を自動的に解決します。パスをハードコードしたり、自分で結果をダウンロードしたりしてはいけません。ユーザーが URL だけを希望すると明示した場合に限り、--download を省略できます。
キー名を推測してはいけません。キー名はアプリごとに異なります。必ず describe の出力から取得してください（エージェント側のみ。キーの綴りに関する作業をユーザーに見せてはいけません）。
アプリを選ぶ前に、アプリの提供元を確認してください。

Official Apps：CawCut の公式アカウントが所有する、厳選されたアプリです。
My Apps：認証済みユーザーが所有するアプリです。
Shared Apps：別のユーザーが認証済みユーザーと共有したアプリです。ユーザーが「official」または「shared」を指定した場合は、cawcut app list の該当セクションからのみ選んでください。

実行を試みる前にローカルメディアを事前検査してはいけません — 実行前に、ローカルファイルのサイズや寸法を確認するために ls / file / sips -g pixelWidth/pixelHeight（または類似のコマンド）をシェルから実行してはいけません。まず cawcut app run を直接実行してください。アップロード前のチェックに失敗した場合は、CLI のエラーに正確なサイズ／寸法と上限がすでに示されています。事前に手動で検査するのではなく、そのエラーに従って対応してください（「エラー」を参照）。

ワークフロー

1. 利用可能なアプリを一覧表示する

cawcut app list --schema
# optional: --category image | --category video

出力：出力カテゴリ（Image Apps／Video Apps）ごとに分類し、その中をソース（Official／My／Shared）ごとに分類したアプリ一覧です。名前、説明、クレジット、利用可能な場合は入力スキーマの行が表示されます（cawcut app list の人間向け出力にはアプリ ID は表示されません）。アプリ名、説明、categories、ソース、クレジット、必須の入力の種類をもとに、候補を特定してください。自動化でアプリ ID が必要な場合は、内部で cawcut app list --json を使用してください。

人間向け出力の例：

Image Apps
  Official Apps
    Photo to Sticker  2 credits  description: Turn a scene photo into a sticker
  My Apps
    My still template  description: Custom image workflow

Video Apps
  Official Apps
    Product video generator  8 credits  description: Generate a product ad video

Official Apps、My Apps、Shared Apps を同じものとして扱わないでください。同じアプリが複数のソースから表示される場合は、CLI に表示されたソースを優先してください。 reply_language が英語以外の場合はアプリ名と説明を翻訳し、入力キーとソースグループ名はそのままにしてください。ユーザーに表示するアプリ一覧にアプリ ID を含めないでください。

ユーザーが自然言語でリクエストを指定した場合は、有力な候補を次の順に並べてください。

該当するものがあれば、最適な公式アプリ／テンプレート。
最適な所有済み／共有アプリ。
該当するアプリがない場合、またはユーザーが生の生成を選んだ場合に限り、cawcut-generate を代替候補として提示します。

明確な候補が1つの場合： 選択済みとして扱い、describe を実行してから、メタデータ＋入力テーブル＋入力選択メニューを提示してください（UX ルール 3）。「このアプリなら…」という説明だけで返答しないでください。

候補が複数の場合： それぞれについて、名前、説明、ソース、クレジット、入力の概要を番号付きリストで提示してください。ユーザーが選んだ後、describe を実行し、入力を収集する前に詳細をすべて提示してください。

ユーザーがリクエストを指定していない場合も、すぐに役立つ選択肢を提示してください。「何を実行しますか？」という内容のない質問はしないでください。

選択肢は reply_language で提示してください。デフォルトの例（スキルを単独で呼び出した場合／英語）：

Here are runnable CawCut Apps:
1. Product video generator — Generate a product ad video
   Source: Official Apps; est. 8 credits; needs: prompt(text), product_image(image)
2. Generate a product ad video — My marketing template
   Source: My Apps; needs: prompt(text)
3. Apply a shared style template — Shared by another user
   Source: Shared Apps; needs: image(image)

You can:
A. Run 1 / 2 / 3 (I'll list required inputs next)
B. Describe your goal and I'll recommend the best App
C. Skip templates and use cawcut-generate instead

その後、ユーザーが別の言語で入力した場合も、同じ構成を reply_language で使用してください。

ユーザーがアプリを選んだ場合（またはアプリが1つ自動で選ばれた場合）は、すぐにそのアプリを確認してください。

cawcut app describe "Product video generator"

続いて、アプリのメタデータテーブル、入力テーブル、入力収集メニューを提示してください（UX ルール 3、11～12）。メニューの選択を通じて必須の入力が確定するまで実行しないでください。自由形式でパラメーターを入力させてはいけません。

例 — ユーザーが動画の最初のフレームをキャプチャするよう依頼した場合（describe の実行後）：

Found a matching App: **First/Last Frame Extractor (qa test)**

| Field | Value |
|-------|-------|
| Name | First/Last Frame Extractor (qa test) |
| Source | Official Apps |
| Cost | … credits |
| Output | First frame + last frame images |

Extracts the first and last frame from a video and outputs them as images.

| Name | Type | Required | Notes |
|------|------|----------|-------|
| … | video | yes | The video to process (MP4, WebM, etc.) |

Provide the video:
A. Use a video already shared in this chat
B. Paste an HTTPS video URL
C. Provide a local file path

2. 入力を確認する

cawcut app describe "<app name>"

出力：KEY、KIND、必須／任意、DEFAULT、DESCRIPTION を含む入力テーブルです。例：

App: Product video generator
Description: Generate a product ad video

Inputs — use the KEY column with --input KEY=value:

  KEY                   KIND    REQ   DEFAULT           DESCRIPTION
  prompt                text    yes   no                Ad script or product description
    requirements: Required text input.
  product_image         image   yes   no                Product photo
    requirements: Required image input. Provide an HTTPS URL, local file path, or {asset_id,url} object.

Run: cawcut app run "Product video generator" --input 'prompt=...' --input 'product_image=@/path/to/file'

生の JSON スキーマを表示する場合（ツールの name に内部アプリ ID が含まれます）：

cawcut app describe "<app name>" --json

アプリ名が重複している場合の曖昧さの解消（必須）

cawcut app describe または cawcut app run が Multiple apps named "..." を返した場合は、確認用のテーブルを提示してください。アプリ ID は引き続き表示しません。

#	名前	ソース	説明	クレジット	入力

CLI のメッセージから、ソース、説明、クレジット、入力スキーマの行を使って各行を埋めてください。番号で選ぶか、どのコピーがよいかを説明するようユーザーに尋ねてください。その後、次を実行してください。

cawcut app run "3D Model Generator" --pick 2 --input ... --wait --download --json

--pick はユーザーの確認後にのみ使用してください。名前が一意の場合は --pick を省略してください。

ユーザーに App の入力を提示する（必須）

CawCut App の入力は cawcut app describe から取得します — KEY/KIND テーブルと要件の行です。専用の model get スタイルのコマンドからすぐに使えるパラメータテーブルを出力する CLI もありますが、CawCut にはありません。App を説明するときは、ユーザー向けの Markdown テーブルを表示してください。CLI の生出力を貼り付けたり、曖昧な文章で済ませたりしないでください。

表示ルール： テーブルは情報の提示に使用します。列挙値または固定値とのやり取りには、常に番号付きメニューを使用します（cawcut-generate と同じです）。テーブルを「各行に入力する」自由入力形式にしないでください。

以下の列構成を使用してください。

名前	型	制約 / 形式	デフォルト	必須	備考

describe / --json からの行の対応：

ソース	テーブル列
JSON の KEY（`properties` のキー）	名前 — `--input` に指定する正確なキー。スペースを含む場合があります — シェルでは引用符で囲みます
`x-cawcut-input-kind` または KIND	型：`text` / `image` / `video` / `audio`
`oneOf` / 要件のテキスト	制約 — `HTTPS URL`、`@/local/path`、`{asset_id,url}`
`x-cawcut-has-default` + デフォルト値	デフォルト — false の場合は `none`
`x-cawcut-required`	必須 — `yes` / `no`
DESCRIPTION + 要件	備考 — ユーザー向けのラベル。`x-cawcut-sample-url` / `sample:` の行はあくまで例示です — `--input` に指定しないでください

App メタデータテーブル — 入力テーブルの上に記載してください。

項目	値
名前	list/describe から取得
ソース	Official Apps / My Apps / Shared Apps
カテゴリ	list JSON の `categories` から取得
コスト	`app list --schema` のクレジット数
出力	image / video / audio / text（`categories` を優先）

ユーザー向けテーブルに App ID を含めないでください。CLI を呼び出す際は、このターンで新たに実行した cawcut app list --json から ID を解決してください。

例 — Photo to Sticker：

項目	値
名前	Photo to Sticker
ソース	Official Apps
コスト	6.9 credits
出力	ステッカー風画像（メタリックな輪郭 + エナメルの縁取り）

名前	型	制約 / 形式	デフォルト	必須	備考
`Input - Scene Photo`	image	HTTPS URL、`@/local/path`（自動アップロード）、`{asset_id,url}`	none	yes	シーン / 人物の写真 → ステッカー効果

ユーザー向けメニュー（テーブルの後）：

Scene photo for Photo to Sticker:
A. Use a photo already shared in this chat
B. Paste an HTTPS image URL
C. Provide a local file path

cawcut app run "Photo to Sticker" \
  --input "Input - Scene Photo=@/path/to/photo.jpg" \
  --wait --download --json

App ごとにキーとクレジット数は環境によって異なるため、必ず実行中の App に対して describe を実行してください。

cawcut app run のCLI フラグテーブル：

名前	型	制約 / オプション	デフォルト	必須	備考
`<app_ref>`	string	list に表示される App 名、または内部 ID	—	yes	スペースを含む場合は引用符で囲みます。名前が曖昧な場合は `--pick <n>` を追加します
`--pick`	number	曖昧さ解消リストでの 1 始まりのインデックス	—	no	複数の App が同じ名前を共有している場合のみ
`--input`	key=value	describe の KEY	—	スキーマによる	繰り返し指定可能。スペースを含むキーは引用符で囲みます
`--input-json`	file	JSON オブジェクト	—	no	`--input` とは相互に排他的です
`--wait`	flag	—	off	推奨	完了まで待機します
`--download`	flag \| path	省略時はシステムの Downloads	off	推奨	メディアの結果を自動保存します
`--json`	flag	—	off	推奨	構造化出力

3. 入力を指定して実行する

実行前の確認（コマンドを組み立てる直前に必ず行ってください）： 現在の subject／goal について、ルーティングやスコアリングの前に、このユーザーメッセージ内で cawcut app list --json を実行しましたか？ いいえの場合、またはこのユーザーメッセージ内で前回のカタログ確認後に subject／goal または対象 App が変更された場合は、ここで処理を中止し、ただちにステップ 1に戻ってください。先に cawcut app run を呼び出してはいけません。以前のユーザーメッセージでのカタログ確認や「該当なし」という結果は、確認済みとは見なされません。run の前に、このターンで対象 App の確認が済んでいない場合は、最新の cawcut app list --json から App ID を特定してください。

CLI がプレーンテキストではなく構造化 JSON を出力するように、必ず --json を指定してください。これにより、エージェントによって署名付きの結果 URL が途中で切り捨てられるのを防げます。

cawcut app run "Product video generator" \
  --input prompt="summer sale, bright colors" \
  --input product_image="https://cdn.example.com/shoe.jpg" \
  --wait --download --json

ローカルファイル（CawCut のアセットに自動アップロードされます）：

cawcut app run "Product video generator" \
  --input prompt="summer sale" \
  --input product_image="@./shoe.jpg" \
  --wait --download --json

複数の入力：

cawcut app run "<app name>" \
  --input key1=value1 \
  --input key2=value2 \
  --wait --download --json

JSON ファイル（キーが多い場合や、特殊文字を含む値を指定する場合の代替方法）：

cawcut app run "<app name>" --input-json ./inputs.json --wait --download --json

inputs.json の形式：

{ "prompt": "...", "product_image": "https://cdn.example.com/img.jpg" }

1 回の呼び出しで --input と --input-json を併用しないでください。

メディアのアップロード前チェックでの失敗（サイズ／寸法） — ローカルの @ パスを指定すると、実行に進む前にアップロードの検証が行われます。CLI がプレーンテキストの制限メッセージ（例：Audio file size is 22.9 MB (limit 15 MB). Re-encode or trim…）を出力し、Code:／Category:／Suggested actions: のマーカーがない場合でも、復旧対応が必要です。エラーをそのまま返すだけにしてはいけません。必ず最初に AskUserQuestion／AskQuestion を呼び出し、今すぐユーザーのために圧縮／サイズ変更（sips／ffmpeg）を行って再試行するか、ユーザー自身に修正してもらうか、キャンセルするかを確認してください。番号付きテキストを使えるのは、ツールを利用できない場合に限ります。CawCut Web は提案しないでください。失敗の種類ごとの正確なコマンドについては、references/troubleshooting.md を参照してください（MB の上限と最長辺の px 制限では、対処方法が異なります）。以下のエラー表でも同じルールが適用されます。

4. 結果をダウンロードする

上記の実行コマンドには、すでに --download が含まれています。CLI が適切なシステムのダウンロードフォルダーを自動的に特定するため、パスの指定は不要です。

5. 結果を渡す

--json を指定すると、CLI は JSON を出力します。

local_path の値は、そのプラットフォーム固有のパスです。macOS では /Users/.../file.png、Windows では C:\Users\...\Downloads\file.png のようになります。CLI が出力したとおりのパスをユーザーに伝えてください。

{
  "result_url": "https://cdn.cawcut.com/...?Expires=...&Signature=...&Key-Pair-Id=...",
  "result_urls": [
    "https://cdn.cawcut.com/...?Expires=...&Signature=...&Key-Pair-Id=...",
    "https://cdn.cawcut.com/...?Expires=...&Signature=...&Key-Pair-Id=..."
  ],
  "task_id": "...",
  "local_path": "/Users/.../file.png",
  "local_paths": ["/Users/.../file-1.png", "/Users/.../file-2.png"],
  "status": "done",
  "credits_used": 12.0,
  "credits_balance": 88.0
}

6. VN スキルに引き継ぐ

結果を渡した後、渡したすべてのローカルパス（local_paths、パスが 1 つだけの場合は local_path）とともに、必ず cawcut-vn に引き継いでください。VN がインストールされているかどうかを含め、プレビューしてインポートするか、編集フローに進むか、何もしないかという VN に関するすべての判断は、このスキルが担当します。ここで VN のメニューを尋ねたり、cawcut vn コマンドを実行したり、引き継ぎ先スキルの選択に対応するために App を再実行したりしないでください（一度だけ判断します）。

入力の種類と形式

種類	`--input` の形式	備考
`text`	`key=some text value`	文字列。数値／ブール値は文字列に変換されます
`image`	`key=https://…` または `key=@/local/path.jpg`	ローカルファイルは自動アップロードされます。URL はそのまま渡されます
`video`	`key=https://…` または `key=@/local/path.mp4`	画像と同じアップロード動作です
`audio`	`key=https://…` または `key=@/local/path.mp3`	画像と同じアップロード動作です

@ プレフィックスは、アップロードするローカルパスであることを明示します。プレフィックスのないパス（例：./file.jpg）も、ファイルが存在する場合は自動検出され、アップロードされます。

非同期タスク

CLI はポーリングを開始する前に、標準出力に必ず Task: <task_id> を出力します。これを取得しておいてください。復旧時に必要となる情報です。

--wait を指定した場合：CLI は処理を完了するまでブロックし、成功するとすべての結果 URL を出力します。
--wait を指定しない場合：CLI は Check status with: cawcut task status <task_id> --wait と出力します。
--wait がタイムアウトした場合：CLI は Polling timed out. Resume with: cawcut task status <task_id> --wait と出力します。処理を再開するには、そのコマンドを実行してください。

エラー

CLI に Code:、Category:、Suggested actions: が表示された場合は、再試行する前に、その番号付きのアクションをユーザーに提示してください。トークン、アプリへのアクセス、入力の不足、入力の無効、クレジット、コンテンツポリシー、タイムアウトのエラーへのフォールバック処理には、references/troubleshooting.md を使用してください。

それ以外の多くのエラーは、これらのマーカーが付かないプレーンテキストの CLI メッセージです。以下の症状→アクション表を使用してください（メディアのアップロード前チェックにおけるサイズ・寸法の制限を含みます）。

JSON に result_urls がある場合は抽出し、すべての URL をユーザーに提示してください。後方互換性のため、result_url は最初の URL です。local_paths がある場合は、すべてのエントリも共有してください。署名付き URL は正確な値を使用してください。切り詰めたり、クエリパラメーターを削除したりしないでください（アクセスには ?Expires=...&Signature=...&Key-Pair-Id=... の部分が必要です）。

必ず同じ JSON の credits_used（ない場合は credits_estimate）と credits_balance（または credits_balance_error）も報告してください。同じセッション内で連続して実行した場合も含め、完了した実行ごとに必ず報告してください。前の実行ですでに表示したからといって、省略しないでください。

症状	アクション
アプリが見つからない	`cawcut app list` を再実行し、アプリ名のスペルを確認する
同じ名前のアプリが複数ある	選択肢を区別する表（ソース、説明、入力）を表示し、ユーザーに確認してから `--pick <n>` を指定して再実行する
アプリが Official Apps にない	My Apps と Shared Apps も確認する。ユーザー所有または共有のアプリも有効ですが、公式アプリとして説明してはいけません。
`unknown input key "..."`	`cawcut app describe "<app name>"` を確認し、キーのスペルを修正する
`Token expired`	Step 0 のログイン手順に従い、`status=authenticated` になった後、失敗したコマンドを一度だけ再試行する
メディアのアップロード前チェックに失敗（サイズ／寸法）	エラーを表示するだけにしてはいけません。必ず最初に `AskUserQuestion` / `AskQuestion` を呼び出し、今すぐユーザーのために圧縮／サイズ変更して（`sips`／`ffmpeg`）再試行するか、ユーザー自身で修正するか、キャンセルするかを尋ねてください。ツールが利用できない場合に限り、番号付きのテキストを使用します。CawCut Web を提案してはいけません。失敗の種類ごとの正確なコマンド（MB の上限と最長辺の px 制限では対処方法が異なります）については、`references/troubleshooting.md` を参照してください。
生成時のモデル制限により実行に失敗	`cawcut capabilities list --models --schema --json` を調べ、`medias[].limit` を確認する。

入力の解決について詳しくは、references/app-inputs.md を参照してください。

Markdown 対応

ログインしてコメント

基本情報

作者: cawcut
リポジトリ: cawcut/skill
カテゴリ: クリエイティブ・メディア
インストール数: 277
GitHub スター: 2

問題を報告