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 propósito geral em especialistas. Diferentemente de prompts (instruções no nível da conversa para tarefas pontuais), 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 no claude.ai, na Claude API, no Claude Platform on AWS e no Microsoft Foundry. No Microsoft Foundry, Agent Skills requerem 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 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 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 e fluxos de trabalho especializados

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 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 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 por 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 referenciarem 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 possibilita:

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 precisa 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 na hora.

Sem limite prático de 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ê consultaria 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: Preenchimento de formulário não é necessário, então FORMS.md não é lido
5. Claude executa: Usa instruções do SKILL.md para completar a tarefa

O diagrama mostra:

1. Estado padrão com prompt do sistema e metadados da 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 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:



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 via API requer três cabeçalhos beta:

• code-execution-2025-08-25 - Skills são executadas no container 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 container

Use Agent Skills pré-construídas referenciando seu skill_id (por exemplo, pptx, xlsx), 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.

Para saber mais, consulte Usar Skills com a Claude API.



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, 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 já estão funcionando nos bastidores quando você cria documentos. O Claude as usa sem exigir nenhuma configuração.

Skills personalizadas: Faça upload de 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, 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 o Claude deve usá-la. Para orientações completas de criação, consulte o guia de melhores práticas.



Considerações de segurança

Use 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 minuciosamente: Revise todos os arquivos incluídos 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 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: 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 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. No Microsoft Foundry, Agent Skills requerem uma implantação Hosted on Anthropic. 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: Fornece ao Claude material de referência atualizado da API, documentação de SDK e melhores práticas para 8 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 Skills cookbook.



Retenção de dados

Agent Skills não é coberto por acordos de ZDR. Definições de Skill 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

Entender essas limitações ajuda você a planejar sua implantação de Skills de forma eficaz. O Claude Platform on AWS e o Microsoft Foundry seguem as mesmas limitações que a Claude API nas subseções a seguir.



Disponibilidade entre superfícies

Skills personalizadas não sincronizam 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

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



Escopo de compartilhamento

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: Em todo o workspace; todos os membros do workspace podem acessar Skills enviadas
• Claude Code: Pessoal (~/.claude/skills/) ou baseado em projeto (.claude/skills/); também pode ser compartilhado via Claude Code Plugins

O claude.ai não suporta gerenciamento centralizado por administradores 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, consulte o artigo de suporte Criar e editar arquivos.
• Claude API:
  • 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:
  • 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