Skills

Skills são recursos reutilizáveis e baseados em sistema de arquivos que fornecem ao seu agente expertise específica de domínio: fluxos de trabalho, contexto e melhores práticas que transformam um agente de uso geral em um especialista. Cada skill que você adiciona incorre em um custo modesto na "context window" (janela de contexto) da sessão, adicionando instruções e metadados que ajudam o modelo a usar a skill. Saiba mais na visão geral de Agent Skills.

As skills chegam ao seu agente de duas maneiras: anexe-as através do array skills do agente, ou carregue-as de um repositório GitHub montado na sessão. As skills anexadas vêm em dois tipos. Todas as skills funcionam da mesma forma: seu agente as invoca automaticamente quando são relevantes para a tarefa.

• Skills pré-construídas da Anthropic: Tarefas comuns de documentos, como manipulação de PowerPoint, Excel, Word e PDF (pptx, xlsx, docx, pdf).
• Skills personalizadas: Skills que você cria e faz upload para seu workspace.

Para aprender como criar skills personalizadas, consulte Agent Skills e Melhores práticas para criação de skills. Para fazer upload de uma skill personalizada para seu workspace, consulte Criar uma skill personalizada.



Criar uma skill personalizada

Uma skill personalizada é um diretório contendo um arquivo SKILL.md mais quaisquer arquivos de suporte, enviado para seu workspace como um arquivo zip ou como arquivos individuais. A criação da skill retorna o ID skill_* que você referencia ao anexá-la a um agente. As skills pré-construídas da Anthropic já estão disponíveis em todos os workspaces e não requerem esta etapa. Para usar apenas skills pré-construídas, pule para Anexar skills a um agente.

A Skills API não requer um cabeçalho beta. O exemplo cURL ainda envia anthropic-beta: skills-2025-10-02, e os comandos beta da CLI e do SDK o adicionam automaticamente; requisições que o incluem continuam funcionando sem alterações.

Estes exemplos omitem o campo opcional display_title, então o título da skill é derivado do SKILL.md. Um display_title passado explicitamente deve ser único entre as skills personalizadas no seu workspace.

ant beta:skills create \
  --file example_skill.zip

Para listar, recuperar, excluir e versionar skills personalizadas, consulte Gerenciando skills personalizadas. Para os esquemas completos de requisição e resposta, consulte a referência da API Create Skill. Os pacotes de skills são enviados diretamente para a Skills API, e não através da Files API.



Anexar skills a um agente

Anexe skills ao criar um agente. Cada sessão suporta até 500 skills, contadas como o conjunto deduplicado entre todos os agentes na sessão (consulte Orquestração multiagente).

Cada entrada no array skills usa os seguintes campos:

ant beta:agents create < agent.yaml

name: Financial Analyst
model: claude-opus-5
system: You are a financial analysis agent.
skills:
  - type: anthropic
    skill_id: xlsx
  - type: custom
    skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
    version: latest



Carregar skills de um repositório GitHub

As skills também podem residir na sua base de código. Quando uma sessão monta um repositório através do recurso github_repository, o diretório raiz .claude/skills do repositório é escaneado no início da sessão, e cada skill encontrada ali fica disponível para o agente. Nenhum upload e nenhuma entrada no array skills do agente são necessários. O agente vê o nome, a descrição e o caminho de cada skill descoberta no sandbox, e lê o SKILL.md da skill quando uma tarefa corresponde, incluindo quaisquer scripts e recursos que a skill fornece. A descoberta depende da ferramenta read do agente do conjunto de ferramentas do agente, que está habilitada por padrão; um agente com read desabilitado não carrega skills do repositório.

A descoberta encontra skills exatamente em .claude/skills/<skill-name>/SKILL.md, um nível de diretório de profundidade na raiz do repositório:

• your-repo/
  • .claude/
    • skills/
      • code-review/
        • SKILL.md
      • release-process/
        • SKILL.md
        • scripts/
          • run_checks.sh
  • src/

Locais que não correspondem a esse layout não são descobertos no início da sessão:

• .claude/skills/SKILL.md: um SKILL.md sem um diretório de skill ao redor dele
• .claude/skills/tools/code-review/SKILL.md: aninhado mais de um nível de diretório de profundidade
• skills/code-review/SKILL.md: um diretório skills fora de .claude

Um diretório .claude/skills em outro lugar no repositório, como dentro de um subdiretório de pacote, não é anunciado no início da sessão; essas skills ainda podem aparecer quando o agente lê arquivos sob essa subárvore.

Skills de repositório usam o mesmo formato SKILL.md que as skills personalizadas que você faz upload. Para o formato e orientações de criação, consulte Agent Skills e Melhores práticas para criação de skills.

Para carregar skills de um repositório, crie uma sessão que o monte. Esta é a mesma requisição mostrada em Acessando o GitHub; mount_path é opcional e o padrão é /workspace/<repo-name>:

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --transform id --raw-output <<'EOF'
resources:
  - type: github_repository
    url: https://github.com/org/repo
    mount_path: /workspace/repo
    authorization_token: ghp_your_github_token
EOF
)

Para repositórios privados, o authorization_token do recurso deve ter acesso ao repositório. Este é o mesmo fluxo de token de acesso pessoal usado para qualquer montagem de repositório; consulte Acessando o GitHub.

As skills descobertas seguem o estado de checkout do repositório: o branch ou commit de checkout quando o recurso define um, caso contrário o branch padrão do repositório. O escaneamento é executado uma vez, quando a sessão inicia. Commits enviados durante a sessão não são detectados; para carregar skills atualizadas, inicie uma nova sessão.

Skills de repositório funcionam junto com skills anexadas através do array skills do agente. Se uma skill de repositório compartilha um nome com uma skill anexada, ou com uma skill de outro repositório montado, ambas ficam disponíveis; cada uma é anunciada com seu próprio caminho.



Próximos passos