# エージェントスキル

> コーディングエージェントに、SDK と OAuth を使った Nodaro での開発を教える、すぐに使える指示ファイルです。Claude Code プラグイン、SDK 入門ガイド、Markdown 版のドキュメントも紹介します。

Source: https://nodaro.ai/ja/docs/developers/agent-skills

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

## 利用できるもの
| リソース | エージェントに与えるもの | 向いている対象 |
| --- | --- | --- |
| Claude Code プラグイン `nodaro` | Nodaro SDK のスキルと、ホスト型 MCP サーバーへの接続 | Claude Code のユーザー |
| `using-nodaro-sdk` スキル | TypeScript SDK `@nodaro/sdk` の組み込み方 | スキルファイルや指示ファイルを読み込めるすべてのエージェント |
| `building-nodaro-oauth-app` スキル | Nodaro インスタンスに対して OAuth 2.0 を実装する方法 | ほかの Nodaro ユーザーの代わりに動作するプロダクト |
| エージェント向け SDK 入門ガイド | 会話に貼り付けて使う、SDK を 1 ページにまとめた概要 | どのエージェントでも、すぐに始めたい場合 |
| Markdown 版のドキュメント | ドキュメントの全ページを、エージェントが読みやすい形式で提供 | Web ページを取得できるエージェント |

## Claude Code プラグインをインストールする
Claude Code で、次のコマンドを実行します。

```text
/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）](https://nodaro.ai/docs/mcp)を参照してください。

## プロジェクトにスキルファイルを追加する
2 つのスキルファイルは、公開リポジトリの [docs/skills フォルダー](https://github.com/nodaroai/app.nodaro.ai/tree/main/docs/skills)にあります。各ファイルの先頭には YAML フロントマターがあり、`name` と、スキルを読み込むタイミングをエージェントに伝える `description` が書かれています。その後に、Markdown の指示が続きます。

### スキルをダウンロードする
`using-nodaro-sdk.md`、`building-nodaro-oauth-app.md`、またはその両方をダウンロードします。

### エージェントがスキルを読み込む場所に保存する
Claude Code では、各ファイルを、スキルと同じ名前のフォルダーに `SKILL.md` として保存します。プロジェクト用なら `.claude/skills/using-nodaro-sdk/SKILL.md` に、すべてのプロジェクトで使うなら `~/.claude/skills/` の下に保存します。プロジェクトのフォルダーをコミットすれば、チーム全員がそのスキルを使えます。ほかのコーディングエージェントでは、ファイルの内容を、そのプロジェクト用のエージェントの指示に追加します。

### 作りたいものを依頼する
たとえば、「この Next.js アプリに、Nodaro で商品画像を生成して進行状況バーを表示するページを追加して」と依頼します。エージェントは、対応するスキルを読み込み、その内容に従います。

### 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 アプリ](https://nodaro.ai/docs/developers/oauth)にあります。

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

```bash
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` を捕捉します。

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

```ts

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 コードジェネレーターで作るには、[ミニアプリを埋め込む](https://nodaro.ai/docs/developers/embed/miniapps)の Markdown を渡します。

## スキルか MCP か
| | エージェントスキル | MCP サーバー |
| --- | --- | --- |
| **エージェントがすること** | Nodaro を呼び出すコードを書く | 会話の中から、Nodaro を直接使う |
| **得られるもの** | 自分のアプリ、スクリプト、連携機能 | Nodaro アカウント内の画像、動画、音声 |
| **認証** | コードが使う個人用 API トークンまたは OAuth トークン | OAuth による、あなた自身のログイン |

Claude Code プラグインなら、両方を利用できます。ほかのエージェントに MCP サーバーを追加するには、[クライアントを接続](https://nodaro.ai/docs/mcp/connect)を参照してください。

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

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

## Frequently asked questions

### Nodaro のエージェントスキルとは何ですか？

Claude Code などのコーディングエージェントが、Nodaro を使った開発を頼まれたときに読み込む、Markdown 形式の指示ファイルです。セットアップの手順、従うべきパターン、避けるべき間違いをエージェントに伝えるので、エージェントが書くコードが最初から動きます。

### Claude Code を Nodaro 向けに設定するいちばん早い方法は何ですか？

Nodaro プラグインをインストールします。/plugin marketplace add nodaroai/app.nodaro.ai を実行してから、/plugin install nodaro を実行してください。1 回のインストールで、Nodaro SDK のスキルと、ホスト型の Nodaro MCP サーバーへの接続が追加されます。

### Claude Code 以外のコーディングエージェントでも、スキルを使えますか？

はい。スキルファイルはただの Markdown なので、プロジェクトの指示を読み込めるエージェントなら、どれでも使えます。どのエージェントでもすぐに始めたい場合は、エージェント向け SDK 入門ガイドを会話に貼り付けてください。

### エージェントスキルと Nodaro MCP サーバーの違いは何ですか？

スキルは、Nodaro を使うコードの書き方をエージェントに教えます。MCP サーバーを使うと、エージェントが Nodaro を直接使い、チャットから画像、動画、音声を生成できます。

### コーディングエージェントは、Nodaro のドキュメントを直接読めますか？

はい。ドキュメントのどのページも、URL の末尾に .md を付けると Markdown で取得できます。また、nodaro.ai/llms.txt には、すべてのページが概要付きで一覧になっています。