エージェントスキル

エージェントスキルは、Claude Code や Cursor などのコーディングエージェントに、Nodaro を使った開発の方法を教える、すぐに使える指示ファイルです。スキルは 1 つのタスクについて、SDK のインストールと認証の方法、従うべきパターン、避けるべき間違いをエージェントに伝えます。タスクは、SDK の組み込みか、OAuth アプリの構築のどちらかです。スキルを一度読み込んだら、作りたいものをエージェントに依頼してください。

利用できるもの

Claude Code プラグインをインストールする

Claude Code で、次のコマンドを実行します。

/plugin marketplace add nodaroai/app.nodaro.ai
/plugin install nodaro

1 回のインストールで、次の 2 つが追加されます。

• Nodaro SDK のスキル：クライアントのセットアップ、非同期の生成、利用できるモデルとクレジットの確認、進行状況の表示、エラー処理、OAuth を扱います。Nodaro、@nodaro/sdk、@nodaro/cli、または app.nodaro.ai との連携に触れると、Claude がこのスキルを読み込みます。
• ホスト型 MCP への接続：https://mcp.nodaro.ai/mcp に接続するので、Claude は Nodaro を直接使うこともできます。AI エージェント（MCP）を参照してください。

プロジェクトにスキルファイルを追加する

2 つのスキルファイルは、公開リポジトリの docs/skills フォルダーにあります。各ファイルの先頭には YAML フロントマターがあり、name と、スキルを読み込むタイミングをエージェントに伝える description が書かれています。その後に、Markdown の指示が続きます。

SDK スキルの内容

using-nodaro-sdk は、エージェントが @nodaro/sdk をアプリケーションに組み込むときに有効になります。対象は、サーバー側の自動化、Nodaro インスタンス上のブラウザーアプリ、サードパーティの OAuth アプリです。このスキルは、次の内容を扱います。

• セットアップと 3 つの認証モード：サーバーで個人用 API トークンか OAuth アクセストークンを使う StaticTokenAuth、自分のインスタンス上のブラウザーアプリで使う supabaseAuth、独自のトークン処理に使う CallbackAuth です。
• クライアントのリソース：workflows、nodes、jobs、executions、characters、apps、oauth、credits などです。
• 型付きのエラー：UnauthorizedError、missingScope を持つ ForbiddenError、required と available を持つ InsufficientCreditsError、RateLimitedError、そして基底の NodaroError です。
• レシピ：ワークフローを実行してポーリングする方法、利用できるノードを調べる方法、runAndWait で 1 つのノードを実行する方法です。
• 推論の強度：言語モデルを使うノード向けの設定です。あわせて、カスタムの fetch とタイムアウトも扱います。
• SDK を使わない場面：プロンプト（Prompt）ノードがストリーミングで返す回答など、トークン単位でストリーミングするエンドポイントです。これらには SDK のメソッドがありません。

OAuth スキルの内容

building-nodaro-oauth-app は、エージェントが Nodaro インスタンスに対して OAuth を実装するときに有効になります。このスキルは、個人用 API トークンではなく OAuth を選ぶべき場面、アプリの登録、スコープ、リダイレクト URL、サーバー側でのコードの交換、トークンの保存、取り消し、よくあるエラー、セキュリティのチェックリストを扱います。完全なリファレンスは、OAuth アプリにあります。

エージェント向け SDK 入門ガイドを貼り付ける

エージェント向け SDK 入門ガイド（SDK agent primer）は、コーディングエージェントのために、SDK を 1 ページにまとめた概要です。@nodaro/sdk パッケージの README と、ターミナルからコピーできるプレーンテキストのファイルにあります。

curl -s https://raw.githubusercontent.com/nodaroai/app.nodaro.ai/main/docs/sdk-agent-primer.txt | pbcopy          # macOS
curl -s https://raw.githubusercontent.com/nodaroai/app.nodaro.ai/main/docs/sdk-agent-primer.txt | xclip -sel clip  # Linux

どのエージェントにも貼り付けられるので、貼り付けたら、作りたいものを依頼してください。この入門ガイドは、次の内容をエージェントに教えます。

• セットアップ：npm install @nodaro/sdk を実行し、設定 › APIトークンで作成したトークンを NODARO_ACCESS_TOKEN 環境変数に入れます。トークンは、決してコードに書き込みません。
• 基本のパターン：生成はすべて非同期です。client.nodes.runAndWait が送信とポーリングを行い、出力を返します。
• モデルの選択：provider を省略すると、プラットフォームのデフォルトのモデルが使われます。または、client.nodes.get(type) と client.credits.modelCosts() から、モデルを選ぶ UI を作ります。
• インターフェースのルール：途中の結果は、できた時点ですぐに表示します。onProgress で進行状況をリアルタイムに表示し、AbortSignal でユーザーがキャンセルできるようにします。
• 音声とオーディオの機能：複数話者の声の差し替えや、分析、差し替え、エクスポートを対話的に進める流れも含みます。
• クレジット：生成にはクレジットがかかるので、InsufficientCreditsError を捕捉します。

入門ガイドが教える基本のパターンは、次のとおりです。

import { createClient, StaticTokenAuth } from "@nodaro/sdk"

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(process.env.NODARO_ACCESS_TOKEN!),
})

const img = await client.nodes.runAndWait("generate-image", {
  prompt: "...", provider: "nano-banana-2",
})
const vid = await client.nodes.runAndWait("generate-video", {
  prompt: "...", imageUrl: img.imageUrl,   // the image becomes the start frame
  provider: "seedance-2-fast", duration: 4,
})
// Outputs are on the resolved object: .imageUrl, .videoUrl, .audioUrl

Markdown 版のドキュメントをエージェントに渡す

• どのページも Markdown で取得できます。URL の末尾に .md を付けます。たとえば https://nodaro.ai/docs/developers/oauth.md です。
• https://nodaro.ai/llms.txt には、ドキュメントの全ページが、1 行の概要付きで一覧になっています。
• https://nodaro.ai/llms-full.txt には、ドキュメント全体が 1 つのファイルにまとめられています。

公開したアプリのカスタムインターフェースを AI コードジェネレーターで作るには、ミニアプリを埋め込むの Markdown を渡します。

スキルか MCP か

Claude Code プラグインなら、両方を利用できます。ほかのエージェントに MCP サーバーを追加するには、クライアントを接続を参照してください。

独自のスキルを書く

Nodaro での作業に役立つスキルは、次の 4 つのルールに従っています。

• 焦点を絞ったトリガー：スキルが担当するタスクでは読み込まれ、関係のない作業では読み込まれないように、description を書きます。
• すぐに実行できる内容：背景の説明だけでなく、具体的な手順とコードをエージェントに渡します。
• 確認できる情報源：スキルが根拠にしているドキュメントのページへのリンクを載せ、エージェントが詳細を確認できるようにします。
• ドキュメントとの同期：スキルが根拠にしているページが変わったら、スキルも更新します。