Claude Skills só funcionam no Claude Code? Onde uma skill roda de verdade

Fala aí, beleza? Tratar skill como um recurso exclusivo do terminal é o mal-entendido que mais faz gente seguir tutorial errado hoje

As Agent Skills foram anunciadas em 16/10/2025 e desde o início nasceram como algo que existe em mais de um produto da Anthropic: claude.ai, Claude Code e API

O formato do arquivo é o MESMO nos três

E esses três não fecham a lista de lugares onde uma skill roda: o Agent SDK, o Cowork e as sessões na nuvem também carregam skill, cada um puxando de um lugar diferente

O que muda é justamente como cada ambiente carrega essa skill, e é aí que mora a confusão: o leitor lê um passo do app, tenta repetir no terminal, não encontra o botão e acha que quebrou alguma coisa

Bora separar isso direito, ambiente por ambiente?

O que é uma skill (e por que o formato é o mesmo em todo lugar)

Uma skill é um diretório

Dentro dele, um arquivo SKILL.md obrigatório funciona como ponto de entrada, com frontmatter e as instruções

O resto é opcional: pastas de apoio como references/, scripts/ e assets/ para o que a skill precisa consultar ou executar

Se você já mexeu com pacote de qualquer gerenciador de dependência, a analogia serve: é uma pasta com um manifesto na frente e os arquivos de apoio atrás

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

E o custo de contexto disso tudo?

Essa é a pergunta que todo mundo faz na hora que pensa em ter dez skills instaladas

O carregamento é sob demanda: o corpo da skill só entra no contexto quando a tarefa realmente pede aquilo

Ou seja, manter várias skills penduradas custa pouco de contexto, porque elas não são despejadas todas de uma vez

A linha do tempo, rapidinho

Anúncio das Agent Skills em 16/10/2025, já com skills pré-construídas de documento e suporte a skills customizadas no claude.ai, no Claude Code e na API

Em 18/12/2025 a Anthropic transformou o Agent Skills em padrão aberto, com especificação e SDK de referência publicados em agentskills.io

Isso explica o motivo do formato ser único: a ideia desde o começo era criar uma vez e usar nos vários lugares 🙂

Onde uma skill roda: Claude Code, claude.ai, API e sessões na nuvem

Cinco linhas, cinco jeitos de carregar a MESMA pasta

Se você guardar UMA linha desse post, guarda essa tabela

A pergunta certa nunca é "como ativo skill", e sim "em qual ambiente eu estou agora?"

Como uma skill entra em ação no Claude Code

No terminal o fluxo é de arquivo, não de botão

1. Crie a pasta da skill com o SKILL.md dentro, escolhendo o escopo:

~/.claude/skills/minha-skill/SKILL.md   # pessoal, vale em toda a máquina
.claude/skills/minha-skill/SKILL.md     # do projeto, versionada no repositório

O erro comum deste passo: procurar tela de upload ou botão de ativar

No Claude Code as skills customizadas são baseadas em arquivos locais e não exigem envio pela API

2. Deixe o Claude usar a skill sozinho quando ela for relevante para a tarefa, ou chame direto:

/nome-da-skill

3. Para skills de terceiros, o caminho é plugin:

/plugin                    # abre a interface, com a aba Discover
/plugin marketplace add    # adiciona um marketplace
/plugin install            # instala o plugin

Antes de instalar, o Claude Code mostra uma seção Will install listando o que aquele plugin adiciona: comandos, agents, skills, hooks e servidores MCP e LSP

Leia essa lista, sério

É o momento em que você descobre que aquele plugin "de uma skill só" trazia mais coisa junto

Se a ideia é justamente garimpar coisa pronta em vez de escrever tudo do zero, eu já mostrei onde baixar skills prontas em outro post

4. Entenda o namespace, porque ele evita briga de nome

Uma skill que veio de plugin fica como nome-do-plugin:nome-da-skill

Exemplo: my-plugin/skills/deploy/SKILL.md vira /my-plugin:deploy e convive numa boa com uma skill deploy que você tem em .claude/skills/

O erro comum deste passo: achar que a skill do projeto "sumiu" quando na verdade tem outra de mesmo nome vindo do plugin

E o que já vem de fábrica?

A Anthropic mantém um marketplace curado oficial, o claude-plugins-official, e ele é registrado pelo próprio Claude Code na primeira execução interativa

Ou seja, pra esse aí você não precisa rodar o /plugin marketplace add do passo anterior

E tem a skill Claude API, que já vem embutida no Claude Code e também está no repositório público anthropics/skills

Se você quiser ver como skills conversam com o resto do setup, eu detalho configurar MCP, skills e subagents por lá

Skills na prática: como isso aparece na minha rotina com Claude Code

No vídeo eu mostro 6 skills que fazem parte da minha rotina, todas do lado do terminal

Rodei tudo com o Claude Code dentro do VS Code, numa pasta de projeto vazia

Comecei por uma skill de brainstorm pra planejar o projeto

Em vez de cuspir código na hora, ela abriu uma sequência de perguntas: uso pessoal ou múltiplos usuários, tipo de autenticação, categorias fixas ou customizáveis, e por aí vai

Respondi tudo com sinceridade, porque a qualidade das respostas define a qualidade do projeto que sai no fim

No fim das perguntas ela gerou a documentação de especificação, que eu revisei antes de liberar a etapa seguinte

Depois acionei uma segunda skill pra transformar aquele documento de design aprovado em plano de implementação, com tarefas em ordem, dependências e critérios de aceitação

Pra executar, pedi que o plano rodasse com subagentes e TDD (teste primeiro, implementação depois), que é a estratégia que eu prefiro quando o projeto tem regra de negócio maior

Tome cuidado com uma coisa: a fase de criação de arquivos pede MUITOS aceites seguidos

Se você não usar o modo de pular confirmações, fica preso clicando

A execução fechou 14 tarefas do plano

Uma delas, a configuração de sessão, ficou rodando por quase 10 minutos

E não, não veio perfeito de primeira: ao criar conta o app jogava pro login e o login voltava erro

Resolvi do jeito mais chato e mais eficaz que existe: colei o erro de volta no Claude Code pra ele analisar e corrigir

Depois disso o app subiu em localhost:3000, cadastrei uma despesa no navegador e confirmei que cadastro e autenticação estavam funcionando

Aí sobrou o problema clássico: interface genérica, sem identidade nenhuma

Esse é o ponto que eu corrijo com uma skill de front-end, em vez de sair instalando pacote

Ativei com um prompt descritivo (visual limpo, modo escuro, sensação de controle financeiro) e a mudança apareceu em tipografia, cores de destaque, cards e navegação

Boa parte das reclamações de "resultado ruim" vem daí, do prompt mal escrito, não da ferramenta

Como quinta frente eu mostro que dá pra criar skill própria no Claude Code, tipo uma skill de segurança sob medida pra stack do projeto

E nada disso é bala de prata: esse caminho custa mais tempo e mais tokens que um prompt direto

Repara no que TODO esse fluxo tem em comum: arquivo local e invocação no terminal

É o modo Claude Code

Nenhum passo dele funciona colando no app

Como ativar e enviar skills no claude.ai

Aqui o caminho é outro, e é justamente o que confunde quem vem do terminal

1. Ligue a execução de código primeiro

Em Free, Pro e Max, isso fica em Settings > Capabilities

Em Team e Enterprise, em Organization settings > Skills

O erro comum deste passo: pular ele

O recurso de skills no claude.ai depende de code execution habilitado

2. Abra Customize > Skills e use o toggle por skill

É liga e desliga, uma por uma

3. Para enviar uma skill customizada, crie um arquivo ZIP da pasta da skill

O erro comum deste passo: montar o ZIP com a pasta aninhada

A pasta da skill precisa estar na RAIZ do ZIP, não dentro de uma subpasta

4. Em Team e Enterprise, o Owner pode provisionar skills pra todo mundo

O caminho é Organization settings > Skills, definindo o estado padrão como ligado ou desligado

As skills provisionadas aparecem automaticamente na lista de cada membro

Skills estão disponíveis nos planos Free, Pro, Max, Team e Enterprise

E no Enterprise ainda dá pra ligar a varredura de skills: o Claude checa cada skill e plugin de terceiros enviado ou editado por membros, procurando conteúdo malicioso antes de rodar

Como declarar skills na API da Anthropic

Na API não tem toggle nem barra: você declara

1. Passe as skills no parâmetro container da Messages API

O array de skills usa type e skill_id como obrigatórios, e version como opcional pra fixar a versão

{
  "container": {
    "skills": [
      {
        "type": "<tipo da skill>",
        "skill_id": "<id da skill>",
        "version": "<opcional, fixa a versão>"
      }
    ]
  }
}

2. Habilite a ferramenta de execução de código, com um modelo compatível

Não é detalhe: é no container dela que a skill roda

O erro comum deste passo: declarar a skill e esquecer a code execution tool

3. Envie os dois cabeçalhos beta

anthropic-beta: skills-2025-10-02
anthropic-beta: files-api-2025-04-14

O primeiro habilita skills

O segundo é necessário pra enviar e baixar arquivos do container

4. Respeite o limite: até 8 skills por requisição

Se o seu agente precisa de mais que isso numa chamada só, o problema provavelmente é de arquitetura, não de limite

Cowork, sessões na nuvem e Agent SDK: de onde vêm as skills

Esses três cenários são híbridos e por isso enganam

Agent SDK

O Agent SDK é construído sobre a mesma base do Claude Code

Na prática, agentes do SDK acessam os mesmos recursos baseados em arquivos: CLAUDE.md, rules, skills e hooks lidos do sistema de arquivos

Se você já sabe montar skill pro Claude Code, você já sabe montar pro SDK

Cowork e sessões na nuvem

Aqui vem a pegadinha: essas sessões NÃO leem o ~/.claude/skills/ da sua máquina

O que elas carregam são as skills habilitadas na sua conta claude.ai, sem nenhuma configuração local

Ou seja, aquela skill pessoal linda que você deixou só na sua máquina simplesmente não existe ali

Sessões na nuvem, parte 2

Além das skills da conta, sessões na nuvem também carregam as skills de projeto commitadas em .claude/skills/ do repositório clonado

A conclusão prática do bloco é curtinha: skill que precisa existir fora da sua máquina vai pro repositório ou vai pra conta

Por que sua skill não aparece (instrução de um produto aplicada no outro)

A skill não aparece na lista do claude.ai

Sintoma: você abre o app e as skills simplesmente não estão lá

Causa: code execution desligado

Solução: ligar em Settings > Capabilities (Free, Pro, Max) ou em Organization settings > Skills (Team e Enterprise), e só depois abrir Customize > Skills

Você digita /nome-da-skill no app e não acontece nada

Sintoma: a barra não invoca skill nenhuma no claude.ai

Causa: invocação direta por /nome-da-skill é do Claude Code

Solução: no app, a skill é ligada pelo toggle em Customize > Skills

Você espera as skills de documento no terminal

Sintoma: procurar pptx, xlsx, docx ou pdf dentro do Claude Code e não achar

Causa: essas skills pré-construídas de documento não estão disponíveis no Claude Code

Solução: usar esse tipo de skill onde ela existe (claude.ai, API, Claude Platform na AWS e Microsoft Foundry)

Sua skill pessoal some no Cowork ou na sessão na nuvem

Sintoma: funciona na sua máquina, morre na nuvem

Causa: esses ambientes não leem ~/.claude/skills/

Solução: habilitar a skill na conta claude.ai, ou commitar em .claude/skills/ do repositório

Duas skills com o mesmo nome

Sintoma: você chama deploy e vem a versão errada

Causa: tem uma skill deploy de plugin e outra de projeto

Solução: usar o namespace do plugin, tipo /my-plugin:deploy, que existe justamente pra elas conviverem

Como prevenir tudo isso

Antes de seguir qualquer tutorial, identifique de QUAL ambiente ele está falando

Menu com toggle é app

Caminho de pasta e barra é terminal

Parâmetro e header é API

Só isso já mata a maior parte do sofrimento 😀

Conclusão

Respondendo a pergunta do título de forma direta: não, Claude Skills não são exclusividade do Claude Code

O formato é o mesmo em todo lugar (um diretório com SKILL.md, carregado sob demanda) e desde 18/12/2025 ele é padrão aberto

O que muda é o ambiente de execução: arquivo local e /nome-da-skill no Claude Code, toggle e ZIP no claude.ai, container mais code execution e headers beta na API, sistema de arquivos no Agent SDK, conta e repositório no Cowork e nas sessões na nuvem

Próximo passo concreto: escolha o ambiente onde o SEU trabalho acontece de verdade, escreva um SKILL.md simples e teste ali antes de sair replicando nos outros

Se for coisa de time, versiona em .claude/skills/ do repositório e pronto, todo mundo tem a mesma skill

Bora testar? até o próximo post!