Agent Skills

Por que usar Skills

Skills são recursos reutilizáveis baseados em sistema de arquivos que fornecem ao Claude expertise específica de domínio: fluxos de trabalho, contexto e melhores práticas que transformam agentes de uso geral em especialistas. Ao contrário de prompts (instruções em nível de conversa para tarefas únicas), Skills são carregadas sob demanda e eliminam a necessidade de fornecer repetidamente as mesmas orientações em múltiplas conversas.

Principais benefícios:

• Especializar o Claude: Adaptar capacidades para tarefas específicas de domínio
• Reduzir repetição: Criar uma vez, usar automaticamente
• Compor capacidades: Combinar Skills para construir fluxos de trabalho complexos

Usando Skills

A Anthropic fornece Agent Skills pré-construídas para tarefas comuns de documentos (PowerPoint, Excel, Word, PDF), e você pode criar suas próprias Skills personalizadas. Ambas funcionam da mesma forma. O Claude as usa automaticamente quando relevante para sua solicitação.

Agent Skills pré-construídas estão disponíveis para todos os usuários no claude.ai e via API do Claude. Veja a seção Skills disponíveis abaixo para a lista completa.

Skills personalizadas permitem que você empacote expertise de domínio e conhecimento organizacional. Elas estão disponíveis em todos os produtos do Claude: crie-as no Claude Code, faça upload via API ou adicione-as nas configurações do claude.ai.

Como as Skills funcionam

Skills aproveitam o ambiente de VM do Claude para fornecer capacidades além do que é possível apenas com prompts. O Claude opera em uma máquina virtual com acesso ao sistema de arquivos, permitindo que Skills existam como diretórios contendo instruções, código executável e materiais de referência, organizados como um guia de integração que você criaria para um novo membro da equipe.

Essa arquitetura baseada em sistema de arquivos permite a divulgação progressiva: o Claude carrega informações em etapas conforme necessário, em vez de consumir contexto antecipadamente.

Três tipos de conteúdo de Skill, três níveis de carregamento

Skills podem conter três tipos de conteúdo, cada um carregado em momentos diferentes:

Nível 1: Metadados (sempre carregados)

Tipo de conteúdo: Instruções. O frontmatter YAML da Skill fornece informações de descoberta:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

O Claude carrega esses metadados na inicialização e os inclui no prompt do sistema. Essa abordagem leve significa que você pode instalar muitas Skills sem penalidade de contexto; o Claude apenas sabe que cada Skill existe e quando usá-la.

Nível 2: Instruções (carregadas quando acionadas)

Tipo de conteúdo: Instruções. O corpo principal do SKILL.md contém conhecimento procedural: fluxos de trabalho, melhores práticas e orientações:

# PDF Processing

## Quick start

Use pdfplumber to extract text from PDFs:

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For advanced form filling, see [FORMS.md](FORMS.md).

Quando você solicita algo que corresponde à descrição de uma Skill, o Claude lê o SKILL.md do sistema de arquivos via bash. Somente então esse conteúdo entra na janela de contexto.

Nível 3: Recursos e código (carregados conforme necessário)

Tipos de conteúdo: Instruções, código e recursos. Skills podem incluir materiais adicionais:

pdf-skill/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
    └── fill_form.py (utility script)

Instruções: Arquivos markdown adicionais (FORMS.md, REFERENCE.md) contendo orientações especializadas e fluxos de trabalho

Código: Scripts executáveis (fill_form.py, validate.py) que o Claude executa via bash; scripts fornecem operações determinísticas sem consumir contexto

Recursos: Materiais de referência como esquemas de banco de dados, documentação de API, templates ou exemplos

O Claude acessa esses arquivos apenas quando referenciados. O modelo de sistema de arquivos significa que cada tipo de conteúdo tem diferentes pontos fortes: instruções para orientação flexível, código para confiabilidade, recursos para consulta factual.

A divulgação progressiva garante que apenas o conteúdo relevante ocupe a janela de contexto em qualquer momento.

A arquitetura de Skills

Skills são executadas em um ambiente de execução de código onde o Claude tem acesso ao sistema de arquivos, comandos bash e capacidades de execução de código. Pense assim: Skills existem como diretórios em uma máquina virtual, e o Claude interage com elas usando os mesmos comandos bash que você usaria para navegar em arquivos no seu computador.

Como o Claude acessa o conteúdo da Skill:

Quando uma Skill é acionada, o Claude usa bash para ler o SKILL.md do sistema de arquivos, trazendo suas instruções para a janela de contexto. Se essas instruções referenciam outros arquivos (como FORMS.md ou um esquema de banco de dados), o Claude lê esses arquivos também usando comandos bash adicionais. Quando as instruções mencionam scripts executáveis, o Claude os executa via bash e recebe apenas a saída (o código do script em si nunca entra no contexto).

O que essa arquitetura permite:

Acesso a arquivos sob demanda: O Claude lê apenas os arquivos necessários para cada tarefa específica. Uma Skill pode incluir dezenas de arquivos de referência, mas se sua tarefa precisar apenas do esquema de vendas, o Claude carrega apenas esse arquivo. O restante permanece no sistema de arquivos consumindo zero tokens.

Execução eficiente de scripts: Quando o Claude executa validate_form.py, o código do script nunca é carregado na janela de contexto. Apenas a saída do script (como "Validation passed" ou mensagens de erro específicas) consome tokens. Isso torna os scripts muito mais eficientes do que fazer o Claude gerar código equivalente dinamicamente.

Sem limite prático para conteúdo incluído: Como os arquivos não consomem contexto até serem acessados, Skills podem incluir documentação abrangente de API, grandes conjuntos de dados, exemplos extensos ou quaisquer materiais de referência que você precisar. Não há penalidade de contexto para conteúdo incluído que não é usado.

Esse modelo baseado em sistema de arquivos é o que faz a divulgação progressiva funcionar. O Claude navega pela sua Skill como você referenciaria seções específicas de um guia de integração, acessando exatamente o que cada tarefa requer.

Exemplo: Carregando uma skill de processamento de PDF

Veja como o Claude carrega e usa uma skill de processamento de PDF:

1. Inicialização: O prompt do sistema inclui: PDF Processing - Extract text and tables from PDF files, fill forms, merge documents
2. Solicitação do usuário: "Extraia o texto deste PDF e resuma-o"
3. Claude invoca: bash: read pdf-skill/SKILL.md → Instruções carregadas no contexto
4. Claude determina: O preenchimento de formulários não é necessário, portanto FORMS.md não é lido
5. Claude executa: Usa instruções do SKILL.md para concluir a tarefa

O diagrama mostra:

1. Estado padrão com prompt do sistema e metadados de skill pré-carregados
2. Claude aciona a skill lendo SKILL.md via bash
3. Claude opcionalmente lê arquivos adicionais incluídos como FORMS.md conforme necessário
4. Claude prossegue com a tarefa

Esse carregamento dinâmico garante que apenas o conteúdo relevante da skill ocupe a janela de contexto.

Onde as Skills funcionam

Skills estão disponíveis em todos os produtos de agente do Claude:

API do Claude

A API do Claude suporta tanto Agent Skills pré-construídas quanto Skills personalizadas. Ambas funcionam de forma idêntica: especifique o skill_id relevante no parâmetro container junto com a ferramenta de execução de código.

Pré-requisitos: Usar Skills via API requer três cabeçalhos beta:

• code-execution-2025-08-25 - Skills são executadas no contêiner de execução de código
• skills-2025-10-02 - Habilita a funcionalidade de Skills
• files-api-2025-04-14 - Necessário para fazer upload/download de arquivos para/do contêiner

Use Agent Skills pré-construídas referenciando seu skill_id (por exemplo, pptx, xlsx), ou crie e faça upload das suas próprias via API de Skills (endpoints /v1/skills). Skills personalizadas são compartilhadas em toda a organização.

Para saber mais, veja Usar Skills com a API do Claude.

Claude Code

O Claude Code suporta apenas Skills personalizadas.

Skills personalizadas: Crie Skills como diretórios com arquivos SKILL.md. O Claude as descobre e usa automaticamente.

Skills personalizadas no Claude Code são baseadas em sistema de arquivos e não requerem uploads via API.

Para saber mais, veja Usar Skills no Claude Code.

Claude Agent SDK

O Claude Agent SDK suporta Skills personalizadas através de configuração baseada em sistema de arquivos.

Skills personalizadas: Crie Skills como diretórios com arquivos SKILL.md em .claude/skills/. Habilite Skills incluindo "Skill" na sua configuração allowed_tools.

Skills no Agent SDK são então descobertas automaticamente quando o SDK é executado.

Para saber mais, veja Agent Skills no SDK.

Claude.ai

O Claude.ai suporta tanto Agent Skills pré-construídas quanto Skills personalizadas.

Agent Skills pré-construídas: Essas Skills já estão funcionando nos bastidores quando você cria documentos. O Claude as usa sem exigir nenhuma configuração.

Skills personalizadas: Faça upload das suas próprias Skills como arquivos zip através de Configurações > Recursos. Disponível nos planos Pro, Max, Team e Enterprise com execução de código habilitada. Skills personalizadas são individuais para cada usuário; elas não são compartilhadas em toda a organização e não podem ser gerenciadas centralmente por administradores.

Para saber mais sobre como usar Skills no Claude.ai, veja os seguintes recursos no Centro de Ajuda do Claude:

• O que são Skills?
• Usando Skills no Claude
• Como criar Skills personalizadas
• Ensine ao Claude sua forma de trabalhar usando Skills

Estrutura de Skill

Toda Skill requer um arquivo SKILL.md com frontmatter YAML:

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this Skill]

Campos obrigatórios: name e description

Requisitos dos campos:

name:

• Máximo de 64 caracteres
• Deve conter apenas letras minúsculas, números e hífens
• Não pode conter tags XML
• Não pode conter palavras reservadas: "anthropic", "claude"

description:

• Deve ser não vazio
• Máximo de 1024 caracteres
• Não pode conter tags XML

A description deve incluir tanto o que a Skill faz quanto quando o Claude deve usá-la. Para orientações completas de criação, veja o guia de melhores práticas.

Considerações de segurança

Recomendamos fortemente usar Skills apenas de fontes confiáveis: aquelas que você mesmo criou ou obteve da Anthropic. Skills fornecem ao Claude novas capacidades através de instruções e código, e embora isso as torne poderosas, também significa que uma Skill maliciosa pode direcionar o Claude a invocar ferramentas ou executar código de maneiras que não correspondem ao propósito declarado da Skill.

Principais considerações de segurança:

• Audite completamente: Revise todos os arquivos incluídos na Skill: SKILL.md, scripts, imagens e outros recursos. Procure padrões incomuns como chamadas de rede inesperadas, padrões de acesso a arquivos ou operações que não correspondem ao propósito declarado da Skill
• Fontes externas são arriscadas: Skills que buscam dados de URLs externas representam risco particular, pois o conteúdo buscado pode conter instruções maliciosas. Mesmo Skills confiáveis podem ser comprometidas se suas dependências externas mudarem ao longo do tempo
• Uso indevido de ferramentas: Skills maliciosas podem invocar ferramentas (operações de arquivo, comandos bash, execução de código) de maneiras prejudiciais
• Exposição de dados: Skills com acesso a dados sensíveis podem ser projetadas para vazar informações para sistemas externos
• Trate como instalar software: Use apenas Skills de fontes confiáveis. Seja especialmente cuidadoso ao integrar Skills em sistemas de produção com acesso a dados sensíveis ou operações críticas

Skills disponíveis

Agent Skills pré-construídas

As seguintes Agent Skills pré-construídas estão disponíveis para uso imediato:

• PowerPoint (pptx): Criar apresentações, editar slides, analisar conteúdo de apresentações
• Excel (xlsx): Criar planilhas, analisar dados, gerar relatórios com gráficos
• Word (docx): Criar documentos, editar conteúdo, formatar texto
• PDF (pdf): Gerar documentos PDF formatados e relatórios

Essas Skills estão disponíveis na API do Claude e no claude.ai. Veja o tutorial de início rápido para começar a usá-las na API.

Exemplos de Skills personalizadas

Para exemplos completos de Skills personalizadas, veja o cookbook de Skills.

Retenção de dados

Agent Skills não é coberto por acordos ZDR. Definições de Skills e dados de execução são retidos de acordo com a política padrão de retenção de dados da Anthropic.

Para elegibilidade ZDR em todos os recursos, veja API e Retenção de Dados.

Limitações e restrições

Entender essas limitações ajuda você a planejar sua implantação de Skills de forma eficaz.

Disponibilidade entre superfícies

Skills personalizadas não sincronizam entre superfícies. Skills carregadas em uma superfície não estão automaticamente disponíveis em outras:

• Skills carregadas no Claude.ai devem ser carregadas separadamente na API
• Skills carregadas via API não estão disponíveis no Claude.ai
• Skills do Claude Code são baseadas em sistema de arquivos e separadas tanto do Claude.ai quanto da API

Você precisará gerenciar e fazer upload de Skills separadamente para cada superfície onde deseja usá-las.

Escopo de compartilhamento

Skills têm diferentes modelos de compartilhamento dependendo de onde você as usa:

• Claude.ai: Apenas usuário individual; cada membro da equipe deve fazer upload separadamente
• API do Claude: Em todo o workspace; todos os membros do workspace podem acessar Skills carregadas
• Claude Code: Pessoal (~/.claude/skills/) ou baseado em projeto (.claude/skills/); também pode ser compartilhado via Claude Code Plugins

O Claude.ai atualmente não suporta gerenciamento centralizado de administrador ou distribuição de Skills personalizadas em toda a organização.

Restrições do ambiente de execução

O ambiente de execução exato disponível para sua skill depende da superfície do produto onde você a usa.

• Claude.ai:
  • Acesso à rede variável: Dependendo das configurações do usuário/administrador, Skills podem ter acesso total, parcial ou nenhum acesso à rede. Para mais detalhes, veja o artigo de suporte Criar e Editar Arquivos.
• API do Claude:
  • Sem acesso à rede: Skills não podem fazer chamadas de API externas ou acessar a internet
  • Sem instalação de pacotes em tempo de execução: Apenas pacotes pré-instalados estão disponíveis. Você não pode instalar novos pacotes durante a execução.
  • Apenas dependências pré-configuradas: Verifique a documentação da ferramenta de execução de código para a lista de pacotes disponíveis
• Claude Code:
  • : Skills têm o mesmo acesso à rede que qualquer outro programa no computador do usuário

Planeje suas Skills para funcionar dentro dessas restrições.

Próximos passos