Agent Skill

Claude Code、Codex、Cursor などの AI コーディングアシスタントを使っているなら、SpicyAPI の Skill を入れることで、SpicyAPI の正しい使い方をアシスタントに教えられます。インストールは一度だけです。そのあとは「自分のアプリに SpicyAPI の画像生成を追加して」と頼むだけで、アシスタントは推測に頼らず、SpicyAPI のルールに従って作業します。

このページは、開発者でなくても読み進められます。ターミナルにコマンドを貼り付けられれば、Skill をインストールできます。

Skill とは

Skill とは、人ではなく AI アシスタントに向けて書かれた指示書をまとめたフォルダーです。新しく来た同僚に渡す業務マニュアルのようなものだと考えてください。Skill 自体が作業をするわけではありませんが、作業をする側に、どんな手順を、どの順番で踏むべきか、そして何を絶対にしてはいけないかを伝えます。

AI アシスタントはプログラミング全般には詳しいものの、SpicyAPI 固有のルールについて信頼できる知識は持っていません。推測に任せると、アシスタントは次のようなことをしかねません。

• 存在しないモデル ID や入力フィールドをでっち上げる
• API キーをコードに直接貼り付ける
• ネットワークが一瞬途切れたあと、同じ有料リクエストを 2 回送り、2 回支払う
• 数日後には使えなくなる結果のリンクを渡してくる

Skill をインストールしておくと、アシスタントは作業を始める前に SpicyAPI のルールを読みます。実際には、次のように動きます。

1. Skill のフォルダーは、アシスタントがセッションの開始時に確認する場所に置かれます。
2. アシスタントは、Skill の 1 段落の概要を読みます。依頼が SpicyAPI に関係する場合は、指示の全文を開きます。あなたが Skill の名前を出す必要はありません。
3. コードを書いたりコマンドを実行したりする間、アシスタントはその指示に従います。

最初に知っておくとよいことが 3 つあります。

• 中身はテキストだけです。 Markdown と YAML のファイルだけで、プログラムもスクリプトも、インストール時に実行されるものも一切ありません。どのファイルもテキストエディターで開けます。中身を参照してください。
• API キーは含まれておらず、どこかを呼び出すこともありません。 Skill 単体では、あなたのアカウントにアクセスすることも、お金を使うこともできません。
• 無料で、オープンソースです。 MIT ライセンスで、npm に @spicyapi/skill として公開し、github.com/spicyapi-ai/spicy-skill で開発しています。

Skill・MCP・SDK・CLI の違い

SpicyAPI には、公式のツールが 4 つあります。それぞれ解決する問題が違い、組み合わせて使うように作られています。

Skill は、このどれかの代わりになるものではありません。アシスタントに、それらの使い方を教えるものです。MCP のツールが接続されていればそれを、1 回限りの操作には CLI を、アプリケーションに組み込むコードにはその言語の SDK を使うよう伝えます。

• Skill だけの場合。 アシスタントはプロジェクトに合った正しい連携コードを書けますが、あなたのアカウントで何かを調べたり、代わりにタスクを実行したりはできません。
• MCP だけの場合。 アシスタントはあなたのアカウントで操作できますが、正しい手順の順番を、毎回自力で考えなければなりません。
• 両方の場合。 アシスタントは代わりに試してみることができ、しかもドキュメントどおりのやり方で行います。アシスタントに実際のタスクを実行させたいなら、両方をインストールしてください。互いに衝突することはありません。

役に立つ場面

左の列はあなたが頼むこと、右の列は、それを実現する間に Skill がアシスタントにさせることです。

Skill がしないこと

• 勝手にお金を使うこと。 Skill はテキストなので、何も呼び出せません。アシスタントが MCP サーバーや CLI と API キーをあわせて持っている場合は、有料のタスクを作成できます。Skill は、依頼の中でその有料の実行がすでに明確に認められている場合を除き、まず価格を見せて、あなたの明示的な確認を得るようアシスタントに指示します。MCP サーバーを使う場合は、それに加えて、有料の操作のたびに、アシスタントが飛ばせない確認で処理が止まります。
• 機能をでっち上げること。 タスクのキャンセル、タスク記録の削除、Webhook の再送など、公開 API が提供していないことを行う呼び出しは書きません。
• アカウントの設定に触れること。 登録、ログイン、支払い、チャージ、チームメンバー、プライバシーに関する依頼、アカウントの閉鎖は、SpicyAPI コンソールで行うものとしてそのまま残します。アシスタントがそれらを自動化しようとすることはありません。
• テストを偽ること。 本物のテストを頼まれた場合は、本物の（あなたの確認を得たうえで、場合によっては有料の）リクエストを送り、実際に起きたことを報告します。モックで通っただけのものを「検証済み」と報告することは決してありません。
• コンテンツ用の設定を追加すること。 SpicyAPI にはコンテンツモードのフラグも、リクエストごとの内容審査もなく、Skill がそれをでっち上げることもありません。何ができるかは、選んだモデルによって決まります。

始める前に

必要なものは 4 つです。インストールに必要なのは、最初の 3 つだけです。

1. Agent Skills に対応した AI コーディングアシスタント。 Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、OpenCode、Windsurf をはじめ、多くのアシスタントが対応しています。Skill は、ツールをまたいで使える Agent Skills のフォルダー形式を採用しているので、この形式を読めるアシスタントならどれでも動きます。自分のアシスタントが対応しているかわからない場合は、そのドキュメントで「skills」を検索してください。

2. Node.js 22 以降。 npx コマンドは Node.js に付属しています。次のコマンドで確認します。

   node --version

   現在、skills インストーラーは Node.js 22.20 以降を、パッケージ自体のインストーラーは 22.13 以降を必要とします。コマンドが見つからない場合やバージョンが低い場合は、nodejs.org から LTS 版をインストールし、新しいターミナルを開いてください。

3. ターミナル。 macOS ではターミナルアプリ、Windows では PowerShell です。プロジェクト単位でインストールしたい場合は、そのプロジェクトのフォルダーでコマンドを実行してください。

4. SpicyAPI の API キー（API を呼び出し始めてから必要）。 Skill のインストールには不要です。キーはコンソールで作成します。キーは sk-spicy- で始まり、一度しか表示されません。SPICY_API_KEY という名前の環境変数に保存し、キーそのものをアシスタントとのチャットに貼り付けることは絶対にしないでください。認証を参照してください。

インストール

インストールの方法は 2 つあります。どちらも同じファイルを配置します。特に理由がなければ、1 つ目の方法を使ってください。

npx skills add spicyapi-ai/spicy-skill

# Claude Code、このプロジェクトだけ
npx skills add spicyapi-ai/spicy-skill --agent claude-code

# Codex、すべてのプロジェクト
npx skills add spicyapi-ai/spicy-skill --agent codex -g

# Claude Code と Codex、すべてのプロジェクト、質問なし
npx skills add spicyapi-ai/spicy-skill --agent claude-code codex -g -y

動作を確認する

npx skills list      # 現在のプロジェクトにインストールされた Skill
npx skills list -g   # すべてのプロジェクト向けにインストールされた Skill

依頼の例

次の例のどれかをアシスタントに貼り付けて、細かい部分を調整してください。Skill を使うべき場面だとアシスタントにわかるよう、依頼の中に SpicyAPI という言葉を入れてください。

使いたいモデルがすでに決まっているなら、モデルページの API タブか、認証付きのライブカタログ（GET /api/v1/models）から正確な ID をコピーして、依頼に入れてください。例では、その ID が入る場所を MODEL_ID_FROM_CATALOG と書いています。これは実在する ID ではなく、仮の値です。ID がわからない場合は、ライブカタログから選ぶようアシスタントに頼んでください。モデルカタログを参照してください。

Next.js アプリに画像エンドポイントを追加する

自分の Next.js アプリに、サーバー側の API ルートを追加してください。テキストのプロンプトを受け取り、モデル MODEL_ID_FROM_CATALOG を使って SpicyAPI で画像を生成し、結果を待って画像のリンクを返すものです。API キーは SPICY_API_KEY から読み取ってください。

Skill がアシスタントに注意させる点：

• キーは SPICY_API_KEY としてサーバーに置いたままにします。Web ページは自分の API ルートを呼び出し、キーを使って SpicyAPI を直接呼び出すことはありません。
• リクエストを組み立てる前に、そのモデルの現在の入力フィールドをライブカタログから読みます。
• まず正確な見積もりを取り、見積額と最大課金額をあなたに見せます。有料のリクエストには、確認済みのその見積もりを付けて送ります。
• 生成 1 回につき冪等キーを 1 つ作り、リクエストがタイムアウトしたら同じキーを使い回します。
• 締め切りを設けて待ち、そのあとでタスクの state を確認します。待機が終わったことと、生成が成功したことは別だからです。

Express で Webhook を使って結果を受け取る

自分の Express サーバーに、SpicyAPI のタスク結果を受け取る Webhook エンドポイントを追加してください。SPICY_WEBHOOK_SECRET を使って署名を検証し、結果のリンクをデータベースに保存するようにしてください。

• JSON としてパースする前に、受け取ったままの生のリクエスト本文に対して署名を検証します。
• 同じイベントが複数回届くことがあるため、配信の request_id を使って重複を無視します。
• 完全で検証済みの Webhook からは、追加の照会をせずに、そのまま結果を読み取ります。

完成した動画を自分のストレージにコピーする

SpicyAPI の動画タスクが成功したら、動画をダウンロードして自分の S3 バケットにアップロードし、SpicyAPI のリンクではなく自分のリンクを保存してください。

• 結果のリンクは一時的なもので、生成されたファイルが保存されるのは約 14 日なので、自分が管理する、長く残るコピーを保存します。
• 結果のリンクからダウンロードするときに、API キーは送りません。
• リンクの期限が切れていたら、新しいリンクを得るために、同じタスクを SpicyAPI にもう一度照会します。リンクを得るためだけに、新しいタスクを作ることはありません。

ユーザーの写真を動画にする

自分のアプリで、ユーザーが写真をアップロードし、それを SpicyAPI で短い動画にできるようにしてください。

• ファイルを base64 としてリクエストに貼り付けるのではなく、まず SpicyAPI にアップロードし、返ってきた spicy:// アドレスをリクエストに入れます。
• アップロードの上限を守ります。画像は 10 MiB、MP4 や WebM の動画と MP3 や WAV の音声は 90 MiB までです。
• すでに公開 HTTPS リンクで公開されている写真なら、アップロードせずにそのまま渡せます。

再試行と残高不足に対処する

SpicyAPI との連携で、失敗に対処できるようにしてください。ネットワークのタイムアウトは二重に支払わずに再試行し、アカウントの残高が足りないときはわかりやすいメッセージを表示し、レート制限にかかったら間隔をあけてください。

• タイムアウトしたあとは同じ冪等キーで再試行するので、再試行によって 2 つ目の有料タスクが作られることはありません。
• 「残高不足」（コード 40201）は再試行しません。ユーザーにはわかりやすいメッセージが表示され、あなたがコンソールでチャージします。
• もう一度試す前に、Retry-After が示す時間だけ待ちます。
• 見積もりの期限が切れたり価格が変わったりした場合（コード 40901）は、価格の確認を省くのではなく、新しい見積もりを取って、もう一度あなたに確認します。
• 失敗したタスクを再試行すると新しいタスクが作られ、もう一度課金されうることを理解しています。そのため、再試行するのは、あなたが新たに試したい場合だけです。

バッチで生成する

products.csv にある 20 個の商品について、SpicyAPI で商品写真を生成してください。同時に実行するのは最大 3 つまでにし、各タスクの ID をログに記録してください。

• SpicyAPI にはバッチ用のエンドポイントがないため、同時に送るリクエストの数を絞って実行します。
• 項目ごとに、専用の冪等キーと専用の価格を用意します。
• タスクが受理されたら、すぐにそのタスク ID を記録します。
• 1 つの項目がタイムアウトしても、復旧させるのはその項目だけで、バッチ全体を送り直すことはありません。

中身

インストールされたフォルダーは、次のような構成です。

spicyapi/
├── SKILL.md
├── references/
│   ├── api-workflows.md
│   └── safety.md
└── agents/
    └── openai.yaml

アシスタントが 2 つのリファレンスファイルを開くのは、作業にそれが必要なときだけです。そのおかげで、アシスタントの作業用の記憶を、あなたのプロジェクトのために空けておけます。インストールする前にファイルを読みたい場合は、npx @spicyapi/skill path を実行してください。パッケージがファイルを置いているフォルダーが表示されます。

Skill はアシスタントに、次の環境変数を使ってコードやツールを設定するよう指示します。Skill 自体は、これらをどれも読みません。

更新と削除

更新

SpicyAPI が推奨する作業の流れが変わると、Skill も変わります。インストール済みのコピーは、自動では更新されません。インストールされたフォルダーにはバージョン番号がないので、最新であることを確実にするには、インストールし直すのがいちばん簡単です。

• npx skills add でインストールした場合： 同じ適用範囲と同じアシスタントで、同じコマンドをもう一度実行します。インストール済みのファイルが、そのときのリポジトリの内容に置き換わります。更新は公開された時点ですぐ反映されるので、待つ必要はありません。

• パッケージのインストーラーでインストールした場合： --force と同じ --target を付けて、もう一度実行します。@latest を付けると、npx はキャッシュされたパッケージを使い回すのではなく、最新のパッケージを取得します。

  npx @spicyapi/skill@latest install --target ~/.claude/skills/spicyapi --force

削除

Skill を削除しても、SpicyAPI のアカウント、API キー、アシスタントがすでに書いたコードには影響しません。

• npx skills add でインストールした場合： 同じプロジェクトフォルダーで、次のコマンドを実行します。グローバルにインストールした場合は -g を付けます。そのあと、spicyapi フォルダーがなくなっていることを確認してください。

  npx skills remove spicyapi

• パッケージのインストーラーでインストールした場合： spicyapi フォルダーを削除します。Finder やエクスプローラーで削除するか、ターミナルから次のように削除します。

  # macOS と Linux：インストールしたフォルダーを指定してください
  rm -rf ~/.agents/skills/spicyapi

  # Windows PowerShell
  Remove-Item -Recurse -Force "$HOME\.agents\skills\spicyapi"

  Enter キーを押す前に、パスを 2 回確認してください。末尾は必ず spicyapi になっていなければなりません。

削除したら新しいセッションを始めて、アシスタントが Skill を使わないようにしてください。

トラブルシューティング

ソースコード

このパッケージは MIT ライセンスで、github.com/spicyapi-ai/spicy-skill で公開のまま開発しています。Skill が実際に配置する指示書を読む、書かれている動作と食い違う点を報告する、変更を提案する——いずれもそこからどうぞ。

次のステップ