# 에이전트 스킬

> 코딩 에이전트가 SDK와 OAuth로 Nodaro 기반 개발을 하도록 가르치는 지침 파일입니다. Claude Code 플러그인, SDK 입문서, Markdown 문서도 소개합니다.

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

**에이전트 스킬**은 Claude Code, Cursor 같은 코딩 에이전트가 Nodaro 기반 개발을 하도록 가르치는 지침 파일입니다. 스킬은 SDK 통합이나 OAuth 앱 개발 같은 하나의 작업에 대해, SDK를 설치하고 인증하는 방법, 따라야 할 패턴, 피해야 할 실수를 에이전트에게 알려 줍니다. 스킬을 한 번 불러온 다음, 만들고 싶은 것을 에이전트에게 요청하세요.

## 제공 항목
| 리소스 | 에이전트가 얻는 것 | 적합한 대상 |
| --- | --- | --- |
| 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 요약 | 어떤 에이전트에서든 빠른 시작 |
| Markdown 문서 | 에이전트가 잘 읽는 형식으로 된 모든 문서 페이지 | 웹 페이지를 가져올 수 있는 에이전트 |

## Claude Code 플러그인 설치
Claude Code에서 다음을 실행하세요.

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

한 번 설치하면 두 가지가 추가됩니다.

- **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)를 참조하세요.

## 프로젝트에 스킬 파일 추가
두 스킬 파일은 공개 저장소의 [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 앱이 이에 해당합니다. 다루는 내용은 다음과 같습니다.

- **설정과 세 가지 인증 방식:** 서버에서 개인 API 토큰이나 OAuth 액세스 토큰과 함께 쓰는 `StaticTokenAuth`, 내 인스턴스의 브라우저 앱에서 쓰는 `supabaseAuth`, 직접 만든 토큰 로직에 쓰는 `CallbackAuth`.
- **클라이언트의 리소스:** `workflows`, `nodes`, `jobs`, `executions`, `characters`, `apps`, `oauth`, `credits` 등.
- **타입이 지정된 오류:** `UnauthorizedError`, `missingScope`가 있는 `ForbiddenError`, `required`와 `available`이 있는 `InsufficientCreditsError`, `RateLimitedError`, 그리고 기본 클래스인 `NodaroError`.
- **레시피:** 워크플로를 실행하고 폴링하기, 사용 가능한 노드 확인하기, `runAndWait`로 단일 노드 실행하기.
- 언어 모델을 사용하는 노드의 **추론 강도**, 그리고 사용자 지정 `fetch`와 타임아웃.
- **SDK를 쓰지 말아야 할 때:** SDK 메서드가 없는 토큰 스트리밍 엔드포인트. 예를 들어 텍스트 생성 - 모든 LLM 노드의 스트리밍 답변이 있습니다.

### OAuth 스킬이 다루는 내용
`building-nodaro-oauth-app`은 에이전트가 Nodaro 인스턴스를 대상으로 OAuth를 구현할 때 활성화됩니다. 개인 API 토큰 대신 OAuth가 알맞은 경우, 앱 등록, 범위, 리디렉션 URL, 서버 측 코드 교환, 토큰 저장, 해지, 자주 발생하는 오류, 보안 체크리스트를 다룹니다. 전체 레퍼런스는 [OAuth 앱](https://nodaro.ai/docs/developers/oauth)에 있습니다.

## SDK 에이전트 입문서 붙여 넣기
**SDK 에이전트 입문서**는 코딩 에이전트를 위한 한 페이지 분량의 SDK 요약입니다. [`@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()`를 사용합니다.
- **인터페이스 규칙:** 각 중간 결과는 생기는 즉시 보여 주고, `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: "gpt-image-2",   // the platform default
})
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`.
- <strong>`https://nodaro.ai/llms.txt`</strong>에는 모든 문서 페이지가 한 줄 요약과 함께 나열되어 있습니다.
- <strong>`https://nodaro.ai/llms-full.txt`</strong>에는 전체 문서가 하나의 파일로 담겨 있습니다.

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 작업에 좋은 스킬은 네 가지 규칙을 따릅니다.

- **명확한 트리거.** 스킬이 해당 작업에서만 불러와지고 관련 없는 작업에서는 불러와지지 않도록 `description`을 작성하세요.
- **실행 가능한 내용.** 배경 설명만이 아니라 구체적인 단계와 코드를 에이전트에게 제공하세요.
- **확인할 출처.** 스킬이 근거로 삼는 문서 페이지에 링크를 걸어, 에이전트가 세부 사항을 확인할 수 있게 하세요.
- **문서와 동기화.** 스킬이 근거로 삼는 페이지가 바뀌면 스킬도 업데이트하세요.

## 자주 묻는 질문

### Nodaro 에이전트 스킬이란 무엇인가요?

Claude Code 같은 코딩 에이전트가 Nodaro 기반으로 무언가를 만들어 달라는 요청을 받았을 때 불러오는 지침 Markdown 파일입니다. 에이전트에게 설정 방법, 따라야 할 패턴, 피해야 할 실수를 알려 주므로, 에이전트가 작성한 코드가 처음부터 제대로 작동합니다.

### Claude Code에서 Nodaro를 가장 빠르게 설정하는 방법은 무엇인가요?

Nodaro 플러그인을 설치하세요. /plugin marketplace add nodaroai/app.nodaro.ai를 실행한 다음 /plugin install nodaro를 실행합니다. 한 번 설치하면 Nodaro SDK 스킬과 호스팅된 Nodaro MCP 서버 연결이 함께 추가됩니다.

### Claude Code가 아닌 다른 코딩 에이전트에서도 스킬을 사용할 수 있나요?

네. 스킬 파일은 일반 Markdown이므로, 프로젝트 지침을 읽는 에이전트라면 어느 것이든 사용할 수 있습니다. 어떤 에이전트에서든 빠르게 시작하려면 SDK 에이전트 입문서를 대화에 붙여 넣으세요.

### 에이전트 스킬과 Nodaro MCP 서버는 어떻게 다른가요?

스킬은 Nodaro를 사용하는 코드를 작성하는 방법을 에이전트에게 가르칩니다. MCP 서버는 에이전트가 채팅에서 바로 Nodaro를 사용해 이미지, 동영상, 오디오를 생성하게 해 줍니다.

### 코딩 에이전트가 Nodaro 문서를 직접 읽을 수 있나요?

네. 모든 문서 페이지는 URL 끝에 .md를 붙이면 Markdown으로 볼 수 있으며, nodaro.ai/llms.txt에는 모든 페이지가 요약과 함께 나열되어 있습니다.