O que é uma SKILL em uma LLM

#IA Generativa
#LLMs

O que é uma SKILL em uma LLM

fonte: https://github.com/aridiosilva/IA_SKILLS/blob/main/README.pt.md

(Figura: Diagrama arquitetura do Claude na implementação do recurso SKILLs que expande o hardness dos modelos AI)

Uma SKILL em uma LLM é um pacote de capacidade plugável que transforma o modelo de um gerador de texto para um agente que age.

O modelo base, os pesos, sabe muito, mas por padrão ele só sabe falar. Ele não sabe como criar um slide, como pesquisar seus emails, como gerar uma imagem transparente, como agendar uma tarefa. A SKILL é a camada de harness — a parte dura, de engenharia, em torno do modelo — que ensina a ele COMO agir.

Pensa assim:

Modelo = cérebro. SKILL = treinamento profissional + caixa de ferramentas + manual de procedimento.

Sem skills, toda LLM é generalista. Com skills, ela vira especialista sob demanda.

O que uma SKILL realmente é

Tecnicamente, uma SKLL não é um prompt. É um artefato de software com 4 partes:

Manifesto: Nome, descrição, quando deve ser ativada. É o que o orquestrador lê para decidir "essa pergunta precisa da skill X?". Ex: shopping -> descrição diz "Use quando o usuário quer encontrar, comprar, comparar produtos..."
Instruções especializadas: Um system prompt de alta prioridade que é injetado SÓ quando a skill é carregada. Ele sobrescreve o comportamento genérico. Ele diz as regras, o fluxo de trabalho, os erros a evitar, o formato de saída. É muito mais detalhado que um prompt normal.
Ferramentas autorizadas: Quais funções ela pode chamar. Uma skill de gmail-search pode chamar busca no Gmail. Uma skill de slides pode chamar um gerador de apresentação. Uma skill de transparent-background-image pode chamar image_gen com parâmetros específicos para PNG RGBA.
Schemas e exemplos: Como interpretar a intenção e como formatar a resposta final. Ex: a skill de local SEMPRE tem que retornar place_id em chip, não só texto.

Conceitos básicos ao redor

a) Harness vs. Weights

Os pesos são "hard" porque são caros de treinar e imutáveis em produção. O harness é "hard" porque é código de produção, testado, com permissões, que estende o que o modelo pode fazer sem precisar re-treinar. Skill é a forma mais segura de escalar capacidade.

b) Roteamento e Ativação

O modelo não carrega todas as skills de uma vez — isso estouraria a janela de contexto e criaria conflito. Existe um roteador que lê sua pergunta e decide: preciso carregar local? shopping? deep-research-report? nenhuma?. Só depois disso as instruções da skill entram.

c) Skill vs. Tool vs. Plugin

Tool: é uma função atômica. Ex: web_search(query).
Plugin (antigo): era basicamente expor uma tool para o modelo.
Skill: é orquestração de alto nível. Ela decide QUAL sequência de tools chamar, COMO pensar, COMO validar, e COMO apresentar. Uma skill pode usar 5 tools diferentes em loop.

Exemplo: a skill deep-research-report usa browser.search + browser.open + síntese + citações + formatação de relatório. A tool sozinha não faria isso.

d) MCP - Model Context Protocol

É o padrão atual que muitas skills usam por baixo. Ele padroniza como o modelo descobre que uma skill existe, que parâmetros ela aceita e que resultado ela devolve. É o "USB-C" das skills.

e) Estado e Memória

Skills boas são stateless por padrão, mas podem ler contexto: seu perfil, suas conversas passadas, arquivos que você subiu. A skill slides que cria um deck sobre seu histórico de vendas precisa disso.

3. Por que isso é tão importante?

Confiabilidade: Sem skill, a LLM improvisa como pesquisar no Gmail. Com skill, ela segue um procedimento validado.
Segurança e Permissão: A skill delimita o que pode ser feito. A skill de ads-audiences-pages nunca vai deletar sua conta, porque ela não tem essa tool.
Composabilidade: Você pode encadear skills. "Pesquise meus concorrentes (rival-watch-2) e crie um pitch deck (slides)". O sistema carrega uma, depois a outra.
Evolução sem re-treino: Quer que a IA aprenda a fazer reservas no OpenTable? Você não re-treina o Llama de 400B. Você cria a skill opentable e pluga.

Em resumo: se a LLM é um ator muito inteligente, a SKILL é o roteiro, o figurino e o cenário que permitem que ele realmente desempenhe um papel específico e entregue um resultado útil, e não só uma boa improvisação.

Aqui está a bibliografia de tudo que usamos na nossa conversa, com links https validados:

## Agent Skills

Agent Skills são capacidades modulares que estendem a funcionalidade do Claude. Cada Skill empacota instruções, metadados e recursos opcionais (scripts, templates) que o Claude usa automaticamente quando relevante.

Para saber como a retenção zero de dados (ZDR) se aplica a este recurso, consulte API e retenção de dados.

### Por que usar Skills

Skills são recursos reutilizáveis baseados em sistema de arquivos que dão ao Claude expertise em domínios específicos: fluxos de trabalho, contexto e melhores práticas que transformam um agente de propósito geral em um especialista. Diferente de prompts (instruções em nível de conversa para tarefas únicas), Skills são carregadas sob demanda, então você não precisa repetir a mesma orientação em todas as conversas.

Principais benefícios:

- **Especialize o Claude:** Adapte capacidades para tarefas específicas de um domínio

- **Reduza repetição:** Crie uma vez, use automaticamente

- **Componha capacidades:** Combine Skills para tarefas complexas e com múltiplas etapas

- Para mais sobre a arquitetura e aplicações reais de Agent Skills, veja o post de engenharia do blog Equipping agents for the real world with Agent Skills.

### 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 no seu ambiente, o Claude a usa automaticamente quando relevante para sua solicitação.

Agent Skills pré-construídas estão disponíveis em claude.ai, na Claude API, na Claude Platform na AWS e no Microsoft Foundry. No Microsoft Foundry, Agent Skills requerem um deployment Hosted on Anthropic. Veja Available Skills para a lista completa.

Skills personalizadas permitem empacotar 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. Na Claude Platform na AWS e no Microsoft Foundry, faça upload de Skills personalizadas através da Skills API.

Comece por aqui:

- Para Agent Skills pré-construídas: Veja o tutorial quickstart para começar a usar PowerPoint, Excel, Word e PDF Skills na API

- Para Skills personalizadas: Veja o Agent Skills Cookbook para aprender como criar suas próprias Skills

### 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 onboarding que você criaria para um novo membro da equipe.

Esta arquitetura baseada em sistema de arquivos permite divulgação progressiva (progressive disclosure): Claude carrega informações em etapas 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:

```yaml

---

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 prompt do sistema. A descrição é 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. Esta 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:

```markdown

# PDF Processing

## Quick start

Use pdfplumber to extract text from PDFs:

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:

text = pdf.pages[0].extract_text()

```

Para preenchimento avançado de formulários, veja [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. Só então esse conteúdo entra na janela de contexto.

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

Skills podem agrupar 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 especializadas e fluxos de trabalho

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

| --- | --- | --- | --- |

| Nível 3+: Recursos | Conforme necessário | Nenhum até ser acessado | Arquivos agrupados. Arquivos de referência são carregados no contexto quando lidos. Scripts são executados via bash, e apenas sua saída entra no contexto |

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

### A arquitetura das 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 em arquivos no seu computador.

Agent Skills Architecture - mostrando como Skills se integram com a configuração do agente e a máquina virtual

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 referenciarem 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 esta 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 resto 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 "Validação aprovada" 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 em tempo real.

- **Sem limite prático de 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):

- **Inicializaçã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.

- **Solicitação do usuário:** "Extract the text from this PDF and summarize it"

- **Claude invoca:** bash: cat pdf-processing/SKILL.md → Instruções carregadas no contexto

- **Claude determina:** Preenchimento de formulário não é necessário, então FORMS.md não é lido

- **Claude executa:** Usa instruções do SKILL.md para completar a tarefa

Skills sendo carregadas na janela de contexto - mostrando o carregamento progressivo de metadados e conteúdo da skill

### Onde as Skills funcionam

Skills estão disponíveis nos produtos de agente do Claude:

Claude Platform na AWS e Microsoft Foundry herdam o mesmo comportamento de Skills da Claude API em todas as seções seguintes.

#### 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 container 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 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 container sandbox sem acesso à rede e sem instalação de pacotes em tempo de execução. Veja Limitações e restrições para detalhes.

Para saber mais, veja Using Agent Skills with the API.

#### Claude Code

Claude Code suporta Skills personalizadas. As Skills pré-construídas de documentos (PowerPoint, Excel, Word, PDF) não estão disponíveis no Claude Code, embora a skill open-source da Claude API venha empacotada com ele. Veja a lista completa de comandos e Skills integrados que vêm com 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 requerem uploads via API: coloque-as em ~/.claude/skills/ (pessoal) ou .claude/skills/ (projeto).

Para saber mais, veja Use Skills in Claude Code.

#### claude.ai

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

Agent Skills pré-construídas: Estas 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 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 o uso de Skills no claude.ai, veja 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 da Skill

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

```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 de campo:

**name:**

- Máximo de 64 caracteres

- Deve conter apenas letras minúsculas, números e hifens

- 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 descrição deve incluir tanto o que a Skill faz quanto quando Claude deve usá-la. Para orientação completa de autoria, veja Skill authoring best practices.

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

Se precisar usar uma Skill de fonte não confiável ou desconhecida, tenha extremo cuidado e audite-a completamente antes do uso. Dependendo do acesso que Claude tem ao executar a Skill, Skills maliciosas podem levar à exfiltração de dados, acesso não autorizado ao sistema ou outros riscos de segurança.

Principais considerações de segurança:

- **Audite minuciosamente:** Revise todos os arquivos agrupados 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:** Seja especialmente cuidadoso ao integrar Skills em sistemas de produção com acesso a dados sensíveis ou operações críticas

Para governança, verificação e orientação de implantação em escala organizacional, veja Skills for enterprise. Organizações Claude Enterprise também podem ativar a verificação de conteúdo de Skills para Skills personalizadas carregadas no claude.ai e Claude Cowork. A verificação não cobre Skills carregadas através da Skills API ou do Claude Console.

### Available Skills

#### 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ção

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

Estas Skills estão disponíveis na Claude API, Claude Platform na AWS, Microsoft Foundry e claude.ai. Veja o tutorial quickstart para começar a usá-las na API.

#### Skills de Código Aberto

Bibliografa

Anthropic - Documentação oficial de Skills - Definição de skills como pastas modulares com instruções, scripts e recursos que o Claude carrega sob demanda.

https://docs.anthropic.com/en/docs/build-with-claude/skills

Anthropic lança Skills - The Decoder - Lançamento em outubro de 2025 explicando como skills transformam LLMs generalistas em agentes especializados.

https://the-decoder.com/anthropic-launches-skills-so-claude-can-automatically-pick-prompts-for-specialized-tasks/

Anthropic Skills - The Landscape - Análise técnica: "Skills are modular, on-demand data that transform general-purpose LLMs into specialized agents".

https://dev.to/dbolotov/anthropic-skills-the-landscape-for-new-models-and-architectures-2ld3

Anthropic torna Skills um padrão aberto - SiliconANGLE - Anthropic abre a especificação de Skills como open standard em dezembro de 2025.

https://siliconangle.com/2025/12/18/anthropic-makes-agent-skills-open-standard/

Criado em Agosto-2026