# Skills para agentes

> Instruções prontas que ensinam agentes de programação a usar o SDK e o OAuth do Nodaro, mais o plugin do Claude Code, o guia do SDK e os docs em Markdown.

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

**Skills para agentes** são arquivos de instruções prontos que ensinam agentes de programação, como o Claude Code e o Cursor, a criar com o Nodaro. Uma skill diz ao agente como instalar e autenticar o SDK, quais padrões seguir e quais erros evitar, para uma tarefa: integrar o SDK ou criar um app OAuth. Carregue uma skill uma vez e depois peça ao agente o que você quer construir.

## O que está disponível
| Recurso | O que ele dá ao agente | Ideal para |
| --- | --- | --- |
| O plugin do Claude Code `nodaro` | A skill do SDK do Nodaro e a conexão com o servidor MCP hospedado | Usuários do Claude Code |
| A skill `using-nodaro-sdk` | Como integrar o SDK para TypeScript, `@nodaro/sdk` | Qualquer agente que leia arquivos de skill ou de instruções |
| A skill `building-nodaro-oauth-app` | Como implementar OAuth 2.0 com uma instância do Nodaro | Produtos que agem em nome de outros usuários do Nodaro |
| O guia do SDK para agentes | Um resumo de uma página do SDK para colar em uma conversa | Começar rápido em qualquer agente |
| A documentação em Markdown | Todas as páginas da documentação, em um formato que os agentes leem bem | Agentes que conseguem buscar páginas da web |

## Instalar o plugin do Claude Code
No Claude Code, execute:

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

Uma única instalação adiciona duas coisas:

- **A skill do SDK do Nodaro:** configuração do cliente, geração assíncrona, descoberta de modelos e de créditos, exibição do progresso, tratamento de erros e OAuth. O Claude a carrega quando você menciona o Nodaro, `@nodaro/sdk`, `@nodaro/cli` ou uma integração com o app.nodaro.ai.
- **A conexão MCP hospedada** com `https://mcp.nodaro.ai/mcp`, para que o Claude também possa usar o Nodaro diretamente. Veja [Agentes de IA (MCP)](https://nodaro.ai/docs/mcp).

## Adicionar um arquivo de skill ao seu projeto
Os dois arquivos de skill ficam na [pasta docs/skills](https://github.com/nodaroai/app.nodaro.ai/tree/main/docs/skills) do repositório público. Cada arquivo começa com um frontmatter YAML: um `name` e uma `description` que diz ao agente quando carregar a skill. Em seguida vêm as instruções em Markdown.

### Baixar a skill
Baixe `using-nodaro-sdk.md`, `building-nodaro-oauth-app.md` ou os dois.

### Salvar onde o seu agente lê skills
No Claude Code, salve cada arquivo como `SKILL.md` em uma pasta com o nome da skill: `.claude/skills/using-nodaro-sdk/SKILL.md` no seu projeto, ou em `~/.claude/skills/` para todos os projetos. Faça commit da pasta do projeto, para que toda a sua equipe receba a skill. Em outro agente de programação, adicione o conteúdo do arquivo às instruções do agente para o projeto.

### Pedir o que você quer construir
Por exemplo: “Adicione a este app Next.js uma página que gera uma imagem de produto com o Nodaro e mostra uma barra de progresso.” O agente carrega a skill correspondente e a segue.

### O que a skill do SDK cobre
A `using-nodaro-sdk` é ativada quando um agente integra o `@nodaro/sdk` a uma aplicação: automação no servidor, um app de navegador em uma instância do Nodaro ou um app OAuth de terceiros. Ela cobre:

- **Configuração e os três modos de autenticação:** `StaticTokenAuth` no servidor, com um token de API pessoal ou de acesso OAuth; `supabaseAuth` em um app de navegador na sua própria instância; e `CallbackAuth` para a sua lógica de token.
- **Os recursos do cliente,** como `workflows`, `nodes`, `jobs`, `executions`, `characters`, `apps`, `oauth` e `credits`.
- **Os erros tipados:** `UnauthorizedError`, `ForbiddenError` com o seu `missingScope`, `InsufficientCreditsError` com `required` e `available`, `RateLimitedError` e o `NodaroError` base.
- **Receitas:** executar um workflow e consultá-lo periodicamente, descobrir os nós disponíveis e executar um único nó com `runAndWait`.
- **Esforço de raciocínio** para os nós que usam um modelo de linguagem, além de `fetch` e timeout personalizados.
- **Quando não usar o SDK:** endpoints com streaming de tokens, como a resposta em streaming do nó **Prompt**, que não têm método no SDK.

### O que a skill de OAuth cobre
A `building-nodaro-oauth-app` é ativada quando um agente implementa OAuth com uma instância do Nodaro. Ela cobre quando preferir OAuth a um token de API pessoal, registro do app, escopos, URL de redirecionamento, troca do código no servidor, armazenamento e revogação de tokens, erros comuns e um checklist de segurança. A referência completa é [Apps OAuth](https://nodaro.ai/docs/developers/oauth).

## Colar o guia do SDK para agentes
O **guia do SDK para agentes** (SDK agent primer) é um resumo de uma página do SDK para agentes de programação. Ele está no README do [pacote `@nodaro/sdk`](https://www.npmjs.com/package/@nodaro/sdk) e em um arquivo de texto simples que você pode copiar de um terminal:

```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
```

Cole o guia em qualquer agente e depois peça o que você quer construir. Ele ensina ao agente:

- **Configuração:** `npm install @nodaro/sdk` e um token de **Configurações › Tokens de API** na variável de ambiente `NODARO_ACCESS_TOKEN`, nunca escrito no código.
- **O padrão principal:** toda geração é assíncrona, e `client.nodes.runAndWait` envia, consulta periodicamente e devolve a saída.
- **Escolha do modelo:** omita `provider` para usar o modelo padrão da plataforma, ou monte um seletor de modelos com `client.nodes.get(type)` e `client.credits.modelCosts()`.
- **Regras de interface:** mostre cada resultado intermediário assim que ele existir, mostre o progresso em tempo real com `onProgress` e deixe o usuário cancelar com um `AbortSignal`.
- **A parte de voz e áudio,** incluindo a troca de voz com vários falantes e o fluxo interativo de análise, troca de voz e exportação.
- **Créditos:** as gerações custam créditos, então trate `InsufficientCreditsError`.

O padrão principal que ele ensina:

```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
```

## Dar a documentação aos agentes em Markdown
- **Toda página está disponível em Markdown.** Adicione `.md` à URL dela, por exemplo `https://nodaro.ai/docs/developers/oauth.md`.
- **`https://nodaro.ai/llms.txt`** lista todas as páginas da documentação com o resumo de uma linha de cada uma.
- **`https://nodaro.ai/llms-full.txt`** contém a documentação completa em um único arquivo.

Para criar uma interface personalizada para um app publicado com um gerador de código de IA, dê a ele o Markdown de [Incorporar um miniapp](https://nodaro.ai/docs/developers/embed/miniapps).

## Skills ou MCP
| | Skills para agentes | O servidor MCP |
| --- | --- | --- |
| **O agente** | Escreve código que chama o Nodaro | Usa o Nodaro diretamente, pela conversa |
| **Você recebe** | O seu próprio app, script ou integração | Imagens, vídeos e áudio na sua conta do Nodaro |
| **Autenticação** | O token de API pessoal ou o token OAuth do seu código | O seu próprio login, por OAuth |

O plugin do Claude Code oferece os dois. Veja [Conectar um cliente](https://nodaro.ai/docs/mcp/connect) para adicionar o servidor MCP a outros agentes.

## Escrever a sua própria skill
Uma boa skill para trabalhar com o Nodaro segue quatro regras:

- **Um gatilho focado.** Escreva a `description` para que a skill seja carregada na tarefa dela, e não em trabalhos sem relação.
- **Conteúdo prático.** Dê ao agente passos concretos e código, não só contexto.
- **Fontes para conferir.** Inclua links para as páginas da documentação em que a skill se baseia, para que o agente possa verificar os detalhes.
- **Em sincronia com a documentação.** Atualize a skill quando as páginas em que ela se baseia mudarem.

## Frequently asked questions

### O que é uma skill de agente do Nodaro?

Um arquivo Markdown de instruções que um agente de programação, como o Claude Code, carrega quando você pede para ele criar algo com o Nodaro. A skill dá ao agente a configuração, os padrões e os erros a evitar, para que o código que ele escreve funcione de primeira.

### Qual é a forma mais rápida de configurar o Claude Code para o Nodaro?

Instale o plugin do Nodaro. Execute /plugin marketplace add nodaroai/app.nodaro.ai e depois /plugin install nodaro. Uma única instalação adiciona a skill do SDK do Nodaro e a conexão com o servidor MCP hospedado do Nodaro.

### As skills funcionam com outros agentes de programação além do Claude Code?

Sim. Os arquivos de skill são Markdown simples, então qualquer agente que leia instruções de projeto pode usá-los. Para começar rápido em qualquer agente, cole o guia do SDK para agentes na conversa.

### Qual é a diferença entre uma skill de agente e o servidor MCP do Nodaro?

Uma skill ensina um agente a escrever código que usa o Nodaro. O servidor MCP permite que um agente use o Nodaro diretamente, para gerar imagens, vídeos e áudio a partir do chat.

### Um agente de programação pode ler a documentação do Nodaro diretamente?

Sim. Toda página da documentação está disponível em Markdown quando você adiciona .md à URL dela, e nodaro.ai/llms.txt lista todas as páginas com o resumo de cada uma.