---
title: Skills
description: Pacotes de skills baseados em sistema de arquivos que injetam expertise de domínio e instruções nos prompts dos agentes.
icon: bolt
mode: "wide"
---
## Visão Geral
Skills são diretórios autocontidos que fornecem aos agentes **instruções, diretrizes e material de referência específicos de domínio**. Cada skill é definida por um arquivo `SKILL.md` com frontmatter YAML e um corpo em markdown.
Quando ativada, as instruções de uma skill são injetadas diretamente no prompt da tarefa do agente — dando ao agente expertise sem exigir alterações de código.
**Skills NÃO são ferramentas.** Este é o ponto de confusão mais comum.
- **Skills** injetam *instruções e contexto* no prompt do agente. Elas dizem ao agente *como pensar* sobre um problema.
- **Ferramentas** dão ao agente *funções chamáveis* para tomar ações (buscar, ler arquivos, chamar APIs).
Frequentemente você precisa de **ambos**: skills para expertise, ferramentas para ação. Eles são configurados independentemente e se complementam.
---
## Início Rápido
### 1. Crie um Diretório de Skill
```
skills/
└── code-review/
├── SKILL.md # Obrigatório — instruções
├── references/ # Opcional — documentos de referência
│ └── style-guide.md
└── scripts/ # Opcional — scripts executáveis
```
### 2. Escreva seu SKILL.md
```markdown
---
name: code-review
description: Guidelines for conducting thorough code reviews with focus on security and performance.
metadata:
author: your-team
version: "1.0"
---
## Diretrizes de Code Review
Ao revisar código, siga esta checklist:
1. **Segurança**: Verifique vulnerabilidades de injeção, bypasses de autenticação e exposição de dados
2. **Performance**: Procure por queries N+1, alocações desnecessárias e chamadas bloqueantes
3. **Legibilidade**: Garanta nomenclatura clara, comentários apropriados e estilo consistente
4. **Testes**: Verifique cobertura adequada de testes para novas funcionalidades
### Níveis de Severidade
- **Crítico**: Vulnerabilidades de segurança, riscos de perda de dados → bloquear merge
- **Major**: Problemas de performance, erros de lógica → solicitar alterações
- **Minor**: Questões de estilo, sugestões de nomenclatura → aprovar com comentários
```
### 3. Anexe a um Agente
```python
from crewai import Agent
from crewai_tools import GithubSearchTool, FileReadTool
reviewer = Agent(
role="Senior Code Reviewer",
goal="Review pull requests for quality and security issues",
backstory="Staff engineer with expertise in secure coding practices.",
skills=["./skills"], # Injeta diretrizes de revisão
tools=[GithubSearchTool(), FileReadTool()], # Permite ao agente ler código
)
```
O agente agora tem tanto **expertise** (da skill) quanto **capacidades** (das ferramentas).
---
## Skills + Ferramentas: Trabalhando Juntos
Aqui estão padrões comuns mostrando como skills e ferramentas se complementam:
### Padrão 1: Apenas Skills (Expertise de Domínio, Sem Ações Necessárias)
Use quando o agente precisa de instruções específicas mas não precisa chamar serviços externos:
```python
agent = Agent(
role="Technical Writer",
goal="Write clear API documentation",
backstory="Expert technical writer",
skills=["./skills/api-docs-style"], # Diretrizes e templates de escrita
# Sem ferramentas necessárias — agente escreve baseado no contexto fornecido
)
```
### Padrão 2: Apenas Ferramentas (Ações, Sem Expertise Especial)
Use quando o agente precisa tomar ações mas não precisa de instruções específicas de domínio:
```python
from crewai_tools import SerperDevTool, ScrapeWebsiteTool
agent = Agent(
role="Web Researcher",
goal="Find information about a topic",
backstory="Skilled at finding information online",
tools=[SerperDevTool(), ScrapeWebsiteTool()], # Pode buscar e extrair dados
# Sem skills necessárias — pesquisa geral não precisa de diretrizes especiais
)
```
### Padrão 3: Skills + Ferramentas (Expertise E Ações)
O padrão mais comum no mundo real. A skill fornece *como* abordar o trabalho; ferramentas fornecem *o que* o agente pode fazer:
```python
from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool
analyst = Agent(
role="Security Analyst",
goal="Audit infrastructure for vulnerabilities",
backstory="Expert in cloud security and compliance",
skills=["./skills/security-audit"], # Metodologia e checklists de auditoria
tools=[
SerperDevTool(), # Pesquisar vulnerabilidades conhecidas
FileReadTool(), # Ler arquivos de configuração
CodeInterpreterTool(), # Executar scripts de análise
],
)
```
### Padrão 4: Skills + MCPs
Skills funcionam junto com servidores MCP da mesma forma que com ferramentas:
```python
agent = Agent(
role="Data Analyst",
goal="Analyze customer data and generate reports",
backstory="Expert data analyst with strong statistical background",
skills=["./skills/data-analysis"], # Metodologia de análise
mcps=["https://data-warehouse.example.com/sse"], # Acesso remoto a dados
)
```
### Padrão 5: Skills + Apps
Skills podem guiar como um agente usa integrações de plataforma:
```python
agent = Agent(
role="Customer Support Agent",
goal="Respond to customer inquiries professionally",
backstory="Experienced support representative",
skills=["./skills/support-playbook"], # Templates de resposta e regras de escalação
apps=["gmail", "zendesk"], # Pode enviar emails e atualizar tickets
)
```
---
## Skills no Nível do Crew
Skills podem ser definidas no crew para aplicar a **todos os agentes**:
```python
from crewai import Crew
crew = Crew(
agents=[researcher, writer, reviewer],
tasks=[research_task, write_task, review_task],
skills=["./skills"], # Todos os agentes recebem essas skills
)
```
Skills no nível do agente têm prioridade — se a mesma skill é descoberta em ambos os níveis, a versão do agente é usada.
---
## 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, experimental
---
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 | Descrição |
| :-------------- | :---------- | :----------------------------------------------------------------------- |
| `name` | Sim | 1–64 chars. Alfanumérico minúsculo e hifens. 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. |
---
## 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`. Os diretórios `scripts/`, `references/` e `assets/` estão disponíveis no `path` da skill para agentes que precisam referenciar arquivos diretamente.
---
## Skills Pré-carregadas
Para mais controle, você pode descobrir e ativar skills programaticamente:
```python
from pathlib import Path
from crewai.skills import discover_skills, activate_skill
# Descobrir todas as skills em um diretório
skills = discover_skills(Path("./skills"))
# Ativá-las (carrega o corpo completo do SKILL.md)
activated = [activate_skill(s) for s in skills]
# Passar para um agente
agent = Agent(
role="Researcher",
goal="Find relevant information",
backstory="An expert researcher.",
skills=activated,
)
```
---
## Como as Skills São Carregadas
Skills usam **divulgação progressiva** — carregando apenas o necessário em cada estágio:
| Estágio | 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 (passando caminhos de diretório via `skills=["./skills"]`), skills são automaticamente descobertas e ativadas. O carregamento progressivo só importa quando usando a API programática.
---
## Skills vs Knowledge
Tanto skills quanto knowledge modificam o prompt do agente, mas servem propósitos diferentes:
| Aspecto | Skills | Knowledge |
| :--- | :--- | :--- |
| **O que fornece** | Instruções, procedimentos, diretrizes | Fatos, dados, informações |
| **Como é armazenado** | Arquivos Markdown (SKILL.md) | Embarcado em banco vetorial (ChromaDB) |
| **Como é recuperado** | Corpo inteiro injetado no prompt | Busca semântica encontra trechos relevantes |
| **Melhor para** | Metodologia, checklists, guias de estilo | Documentos da empresa, info de produto, dados de referência |
| **Definido via** | `skills=["./skills"]` | `knowledge_sources=[source]` |
**Regra prática:** Se o agente precisa seguir um *processo*, use uma skill. Se o agente precisa consultar *dados*, use knowledge.
---
## Perguntas Frequentes
Depende do seu caso de uso. Skills e ferramentas são **independentes** — você pode usar qualquer um, ambos ou nenhum.
- **Apenas skills**: Quando o agente precisa de expertise mas não de ações externas (ex: escrever com diretrizes de estilo)
- **Apenas ferramentas**: Quando o agente precisa de ações mas não de metodologia especial (ex: busca simples na web)
- **Ambos**: Quando o agente precisa de expertise E ações (ex: auditoria de segurança com checklists específicas E capacidade de escanear código)
**Não.** O campo `allowed-tools` no SKILL.md é apenas metadado experimental — ele não provisiona nem injeta nenhuma ferramenta. Você deve sempre definir ferramentas separadamente via `tools=[]`, `mcps=[]` ou `apps=[]`.
A skill no nível do agente tem prioridade. Skills são deduplicadas por nome — as skills do agente são processadas primeiro, então se o mesmo nome de skill aparece em ambos os níveis, a versão do agente é usada.
Há um aviso suave em 50.000 caracteres, mas sem limite rígido. Mantenha skills focadas e concisas para melhores resultados — injeções de prompt muito grandes podem diluir a atenção do agente.