> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Pacotes de skills baseados em sistema de arquivos que injetam contexto nos prompts dos agentes.

## Visão Geral

Skills são diretórios autocontidos que fornecem aos agentes instruções, referências e assets específicos de domínio. Cada skill é definida por um arquivo `SKILL.md` com frontmatter YAML e um corpo em markdown.

Skills usam **divulgação progressiva** — metadados são carregados primeiro, instruções completas apenas quando ativadas, e catálogos de recursos apenas quando necessário.

## Estrutura de Diretório

```
my-skill/
├── SKILL.md            # Obrigatório — frontmatter + instruções
├── scripts/            # Opcional — scripts executáveis
├── references/         # Opcional — documentos de referência
└── assets/             # Opcional — arquivos estáticos (configs, dados)
```

O nome do diretório deve corresponder ao campo `name` no `SKILL.md`.

## Formato do SKILL.md

```markdown theme={null}
---
name: my-skill
description: Descrição curta do que esta skill faz e quando usá-la.
license: Apache-2.0                    # opcional
compatibility: crewai>=0.1.0          # opcional
metadata:                              # opcional
  author: your-name
  version: "1.0"
allowed-tools: web-search file-read   # opcional, delimitado por espaços
---

Instruções para o agente vão aqui. Este corpo em markdown é injetado
no prompt do agente quando a skill é ativada.
```

### Campos do Frontmatter

| Campo           | Obrigatório | Restrições                                                                                                                    |
| :-------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------- |
| `name`          | Sim         | 1–64 chars. Alfanumérico minúsculo e hifens. Sem hifens iniciais/finais/consecutivos. Deve corresponder ao nome do diretório. |
| `description`   | Sim         | 1–1024 chars. Descreve o que a skill faz e quando usá-la.                                                                     |
| `license`       | Não         | Nome da licença ou referência a um arquivo de licença incluído.                                                               |
| `compatibility` | Não         | Máx 500 chars. Requisitos de ambiente (produtos, pacotes, rede).                                                              |
| `metadata`      | Não         | Mapeamento arbitrário de chave-valor string.                                                                                  |
| `allowed-tools` | Não         | Lista de ferramentas pré-aprovadas delimitada por espaços. Experimental.                                                      |

## Uso

### Skills no Nível do Agente

Passe caminhos de diretório de skills para um agente:

```python theme={null}
from crewai import Agent

agent = Agent(
    role="Researcher",
    goal="Find relevant information",
    backstory="An expert researcher.",
    skills=["./skills"],  # descobre todas as skills neste diretório
)
```

### Skills no Nível do Crew

Caminhos de skills no crew são mesclados em todos os agentes:

```python theme={null}
from crewai import Crew

crew = Crew(
    agents=[agent],
    tasks=[task],
    skills=["./skills"],
)
```

### Skills Pré-carregadas

Você também pode passar objetos `Skill` diretamente:

```python theme={null}
from pathlib import Path
from crewai.skills import discover_skills, activate_skill

skills = discover_skills(Path("./skills"))
activated = [activate_skill(s) for s in skills]

agent = Agent(
    role="Researcher",
    goal="Find relevant information",
    backstory="An expert researcher.",
    skills=activated,
)
```

## Como as Skills São Carregadas

Skills carregam progressivamente — apenas os dados necessários em cada etapa são lidos:

| Etapa      | O que é carregado                      | Quando              |
| :--------- | :------------------------------------- | :------------------ |
| Descoberta | Nome, descrição, campos do frontmatter | `discover_skills()` |
| Ativação   | Texto completo do corpo do SKILL.md    | `activate_skill()`  |

Durante a execução normal do agente, skills são automaticamente descobertas e ativadas. Os diretórios `scripts/`, `references/` e `assets/` estão disponíveis no `path` da skill para agentes que precisam referenciar arquivos diretamente.