crewAI/docs/v1.12.2/pt-BR/concepts/skills.mdx

---
title: Skills
description: Pacotes de skills baseados em sistema de arquivos que injetam contexto nos prompts dos agentes.
icon: bolt
mode: "wide"
---

## 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
---
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
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
from crewai import Crew

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

### Skills Pré-carregadas

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

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