Agent Skills



Por que usar Skills

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 de prompts (instruções em nível de conversa para tarefas pontuais), Skills são carregadas sob demanda, então você não precisa repetir a mesma orientação em várias conversas.

Principais benefícios:

• Especialize Claude: Adapte capacidades para tarefas específicas de domínio
• Reduza repetição: Crie uma vez, use automaticamente
• Componha capacidades: Combine Skills para tarefas complexas de múltiplas etapas



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: uma vez que uma Skill está disponível em seu ambiente, 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, no Claude Platform on AWS e no Microsoft Foundry. No Microsoft Foundry, 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 através da Claude API ou adicione-as nas configurações do claude.ai. No Claude Platform on AWS e no Microsoft Foundry, faça upload de Skills personalizadas através da Skills API.



Como as Skills funcionam

Skills usam o ambiente de VM do Claude para fornecer capacidades além do que é possível apenas com prompts. 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: Claude carrega informações em estágios conforme necessário, em vez de consumir contexto antecipadamente.

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

Claude carrega esses metadados na inicialização e os inclui no "system prompt" (prompt do sistema). A description é o que Claude compara com sua solicitação ao determinar se deve acionar a Skill, então 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 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, Claude lê o SKILL.md do sistema de arquivos usando bash. Somente então esse conteúdo entra na "context window" (janela de contexto).



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

Skills podem agrupar materiais adicionais:

pdf-processing/
├── 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 e fluxos de trabalho especializados

Código: Scripts executáveis (fill_form.py, validate.py) que 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

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 a qualquer momento.



A arquitetura de Skills

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

Como Claude acessa o conteúdo da Skill:

Quando uma Skill é acionada, 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), Claude lê esses arquivos também usando comandos bash adicionais. Quando as instruções mencionam scripts executáveis, Claude os executa através do 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: Claude lê apenas os arquivos 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 Claude carrega. O restante permanece no sistema de arquivos e custa zero tokens.
• Execução eficiente de scripts: Quando 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 Claude gerar código equivalente na hora.
• Sem limite prático para conteúdo agrupado: Arquivos não consomem contexto até serem acessados, então Skills podem incluir documentação abrangente de API, grandes conjuntos de dados ou exemplos extensos. Não há penalidade de contexto para conteúdo agrupado que não é usado.



Exemplo: Carregando uma Skill de processamento de PDF

Veja como 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. Claude invoca: bash: cat pdf-processing/SKILL.md → Instruções carregadas no contexto
4. Claude determina: O preenchimento de formulários não é necessário, então FORMS.md não é lido
5. Claude executa: Usa as instruções do SKILL.md para completar a tarefa



Onde as Skills funcionam

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 através da API requer a ferramenta de execução de código, em cujo contêiner as Skills são executadas, e um cabeçalho beta:

• skills-2025-10-02 - Habilita a funcionalidade de Skills

Adicione um segundo cabeçalho, files-api-2025-04-14, quando você usar a Files API para fazer upload de arquivos de entrada para o contêiner ou baixar arquivos que uma Skill produz.

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 através da Skills API (endpoints /v1/skills). Skills personalizadas são compartilhadas em todo o workspace: todos os membros do workspace podem acessá-las.

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 Claude API skill de código aberto venha incluída com ele. 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. Claude as descobre e usa automaticamente.

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

Para saber mais, consulte Use 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. Claude as usa sem necessidade de configuração.

Skills personalizadas: Faça upload de suas próprias Skills como arquivos zip através de 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:

• O que são Skills?
• Usando Skills no Claude
• Como criar Skills personalizadas
• Ensine ao Claude sua forma de trabalhar usando 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 Claude deve usá-la. Para orientações completas de criação, consulte Melhores práticas para criação de Skills.



Considerações de segurança

Use Skills apenas de fontes confiáveis: aquelas que você mesmo criou ou obteve da Anthropic. Skills dão ao Claude novas capacidades através de instruções e código, o que também significa que uma Skill maliciosa pode direcionar 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 agrupados na Skill: SKILL.md, scripts, imagens e outros recursos. Procure por 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: Seja especialmente cuidadoso 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.



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, no 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:

• Claude API skill: 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 com o 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 Skills cookbook.



Retenção de dados

Agent Skills não é coberto por acordos de 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 de ZDR em todos os recursos, consulte API e retenção de dados.



Limitações e restrições

Claude Platform on AWS e Microsoft Foundry seguem as mesmas limitações que a 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 em outras:

• Skills enviadas para o claude.ai devem ser enviadas separadamente para a API
• Skills enviadas através da 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

Gerencie e faça upload de Skills separadamente para cada superfície onde você 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.
• Claude API: Em todo o workspace. Todos os membros do workspace podem acessar as Skills enviadas.
• Claude Code: Pessoal (~/.claude/skills/) ou baseado em projeto (.claude/skills/). Também podem ser compartilhadas através 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 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, consulte o artigo de suporte Create and Edit Files.
• Claude API:
  • Sem acesso à rede: Skills não podem fazer chamadas de API 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: Skills têm o mesmo acesso à rede que qualquer outro programa no computador do usuário.
  • Instalação global de pacotes desencorajada: 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