Agent Skills

Por que usar Skills

"Agent Skills" (habilidades de agente), ou Skills, são recursos reutilizáveis, baseados em sistema de arquivos, que dão ao Claude expertise específica de domínio: fluxos de trabalho, contexto e melhores práticas que transformam um agente de propósito geral em um especialista. Diferentemente dos prompts (instruções no nível da conversa para tarefas pontuais), as Skills são carregadas sob demanda, então você não precisa repetir as mesmas orientações em várias conversas.

Principais benefícios:

• Especializar o Claude: Adapte capacidades para tarefas específicas de domínio
• Reduzir repetição: Crie uma vez, use automaticamente
• Compor capacidades: Combine Skills para tarefas complexas de várias etapas

Usando Skills

A Anthropic fornece Agent Skills pré-construídas para tarefas comuns com documentos (PowerPoint, Excel, Word, PDF), e você pode criar suas próprias Skills personalizadas. Ambas funcionam da mesma forma: uma vez que uma Skill está disponível no seu ambiente, o Claude a usa automaticamente quando relevante para sua solicitação.

Agent Skills pré-construídas estão disponíveis no claude.ai, na Claude API, na Claude Platform on AWS e no Microsoft Foundry. No Microsoft Foundry, as Agent Skills exigem uma implantação Hosted on Anthropic. Consulte Skills disponíveis 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 delas pela Claude API ou adicione-as nas configurações do claude.ai. Na Claude Platform on AWS e no Microsoft Foundry, faça upload de Skills personalizadas pela Skills API.

Como as Skills funcionam

As Skills usam 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 as 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 possibilita a "progressive disclosure" (divulgação progressiva): o Claude carrega informações em etapas conforme necessário, em vez de consumir contexto antecipadamente.

As Skills podem conter três tipos de conteúdo, cada um carregado em um momento diferente:

Nível 1: Metadados (sempre carregados)

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. A description é o que o Claude compara com sua solicitação ao determinar se deve acionar a Skill, portanto ela deve dizer tanto o que a Skill faz quanto quando usá-la. Essa abordagem leve significa que você pode instalar muitas Skills sem penalidade de contexto: até que uma Skill seja acionada, apenas seu nome e descrição ocupam contexto.

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

O corpo principal do SKILL.md contém conhecimento procedimental: 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 usando bash. Só então esse conteúdo entra na "context window" (janela de contexto).

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

As Skills podem incluir materiais adicionais:

• pdf-processing/
  • SKILL.md (instruções principais)
  • FORMS.md (guia de preenchimento de formulários)
  • REFERENCE.md (referência detalhada da API)
  • scripts/
    • fill_form.py (script utilitário)

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

Código: Scripts executáveis (fill_form.py, validate.py) que o Claude executa usando bash, fornecendo operações determinísticas sem carregar seu código no 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 pontos fortes diferentes: 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 das Skills

As 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. As 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 pelos 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 também lê esses arquivos 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 possibilita:

• Acesso a arquivos sob demanda: O Claude lê apenas os arquivos de que cada tarefa precisa. Uma Skill pode incluir dezenas de arquivos de referência, mas se sua tarefa precisa apenas do esquema de vendas, esse é o único arquivo que o Claude carrega. O restante permanece no sistema de arquivos e custa 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 sua saída (como "Validation passed" ou uma mensagem de erro específica) consome tokens, o que torna os scripts muito mais eficientes do que fazer o Claude gerar código equivalente na hora.
• Sem limite prático para conteúdo incluído: Os arquivos não consomem contexto até serem acessados, então as Skills podem incluir documentação de API abrangente, grandes conjuntos de dados ou exemplos extensos. Não há penalidade de contexto para conteúdo incluído que não é usado.

Exemplo: Carregando uma Skill de processamento de PDF

Veja como o Claude carrega e usa a Skill personalizada pdf-processing dos exemplos anteriores (não a Skill pré-construída pdf):

1. Inicialização: O prompt do sistema inclui: pdf-processing - 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.
2. Solicitação do usuário: "Extraia o texto deste PDF e resuma-o"
3. O Claude invoca: bash: cat pdf-processing/SKILL.md → Instruções carregadas no contexto
4. O Claude determina: O preenchimento de formulários não é necessário, então FORMS.md não é lido
5. O Claude executa: Usa as instruções do SKILL.md para concluir a tarefa

Onde as Skills funcionam

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

Claude API

A Claude API 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 pela API requer a ferramenta de execução de código, em cujo contêiner as Skills são executadas.

Use Agent Skills pré-construídas referenciando seu skill_id (pptx, xlsx, docx ou pdf), ou crie e faça upload das suas próprias pela Skills API (endpoints /v1/skills). Skills personalizadas são compartilhadas em todo o workspace: todos os membros do workspace podem acessá-las.

As Skills na API são executadas em um contêiner isolado (sandbox) sem acesso à rede e sem instalação de pacotes em tempo de execução. Consulte Limitações e restrições para detalhes.

Para saber mais, consulte Usando Agent Skills com a API.

Claude Code

O Claude Code suporta Skills personalizadas. As Skills de documentos pré-construídas (PowerPoint, Excel, Word, PDF) não estão disponíveis no Claude Code, embora a skill Claude API de código aberto venha incluída nele. Consulte a lista completa de comandos e Skills integrados que acompanham o Claude Code.

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

As Skills personalizadas no Claude Code são baseadas em sistema de arquivos e não exigem uploads pela API: coloque-as em ~/.claude/skills/ (pessoal) ou .claude/skills/ (projeto).

Para saber mais, consulte Usar Skills no Claude Code.

claude.ai

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

Agent Skills pré-construídas: Essas Skills ficam ativas quando você cria documentos. O Claude as usa sem necessidade de configuração.

Skills personalizadas: Faça upload das suas próprias Skills como arquivos zip em Settings > Features. 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 o uso de Skills no claude.ai, consulte os seguintes recursos na Central de Ajuda do Claude:

• What are Skills?
• Using Skills in Claude
• How to create custom Skills
• Teach Claude your way of working using Skills

Estrutura de uma 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:

• Não pode estar 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 autoria, consulte Melhores práticas de autoria de Skills.

Considerações de segurança

Use Skills apenas de fontes confiáveis: aquelas que você mesmo criou ou obteve da Anthropic. As Skills dão ao Claude novas capacidades por meio de instruções e código, o que 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 minuciosamente: 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 um 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 instalação de software: Tenha cuidado especial ao integrar Skills em sistemas de produção com acesso a dados sensíveis ou operações críticas

Para orientações de governança, verificação e implantação em escala organizacional, consulte Skills para empresas. Organizações Claude Enterprise também podem ativar a verificação de conteúdo de Skills para Skills personalizadas enviadas no claude.ai e no Claude Cowork. A verificação não cobre Skills enviadas pela Skills API ou pelo Claude Console.

Skills disponíveis

Agent Skills pré-construídas

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

• PowerPoint (pptx): Crie apresentações, edite slides, analise conteúdo de apresentações
• Excel (xlsx): Crie planilhas, analise dados, gere relatórios com gráficos
• Word (docx): Crie documentos, edite conteúdo, formate texto
• PDF (pdf): Gere documentos e relatórios PDF formatados

Essas Skills estão disponíveis na Claude API, na Claude Platform on AWS, no Microsoft Foundry e no claude.ai. Consulte o tutorial de início rápido para começar a usá-las na API.

Skills de código aberto

A Anthropic também publica Skills de código aberto no repositório de skills:

• Skill Claude API: Fornece ao Claude material de referência atualizado da API, documentação de SDK e melhores práticas para oito linguagens de programação. Incluída no Claude Code e também disponível para instalação a partir do repositório de skills.

Exemplos de Skills personalizadas

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

Retenção de dados

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

Para a elegibilidade de ZDR em todos os recursos, consulte API e retenção de dados.

Para o registro de auditoria das operações da Skills API, consulte Registro de auditoria em Usando Agent Skills com a API.

Limitações e restrições

A Claude Platform on AWS e o Microsoft Foundry seguem as mesmas limitações da Claude API nas subseções a seguir.

Disponibilidade entre superfícies

Skills personalizadas não são sincronizadas entre superfícies. Skills enviadas para uma superfície não ficam automaticamente disponíveis nas outras:

• Skills enviadas para o claude.ai devem ser enviadas separadamente para a API
• Skills enviadas pela API não ficam disponíveis no claude.ai
• As Skills do Claude Code são baseadas em sistema de arquivos e separadas tanto do claude.ai quanto da API

Gerencie e faça upload das Skills separadamente para cada superfície onde você deseja usá-las.

Escopo de compartilhamento

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

• claude.ai: Apenas usuário individual. Cada membro da equipe deve fazer upload separadamente.
• Claude API: Todo o workspace. Todos os membros do workspace podem acessar as Skills enviadas.
• Claude Code: Pessoal (~/.claude/skills/) ou por projeto (.claude/skills/). Também podem ser compartilhadas por meio de Plugins do Claude Code.

O claude.ai não suporta gerenciamento centralizado por administradores nem 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 de produto onde você a usa.

• claude.ai:
  • Acesso à rede variável: Dependendo das configurações do usuário/administrador, as Skills podem ter acesso total, parcial ou nenhum acesso à rede. Para mais detalhes, consulte o artigo de suporte Create and Edit Files.
• Claude API:
  • Sem acesso à rede: As Skills não podem fazer chamadas a APIs externas nem 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:
  • Acesso total à rede: As Skills têm o mesmo acesso à rede que qualquer outro programa no computador do usuário.
  • Instalação global de pacotes desencorajada: As Skills devem instalar pacotes apenas localmente para evitar interferir no computador do usuário.

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

Próximos passos