Skills - CrewAI

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

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

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:

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:

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:

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:

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:

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:

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

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

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

Preciso definir skills E ferramentas?

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)

Skills fornecem ferramentas automaticamente?

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=[].

O que acontece se eu definir a mesma skill tanto no agente quanto no crew?

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.

Qual o tamanho máximo do corpo do SKILL.md?

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.

​Visão Geral

​Início Rápido

​1. Crie um Diretório de Skill

​2. Escreva seu SKILL.md

​3. Anexe a um Agente

​Skills + Ferramentas: Trabalhando Juntos

​Padrão 1: Apenas Skills (Expertise de Domínio, Sem Ações Necessárias)

​Padrão 2: Apenas Ferramentas (Ações, Sem Expertise Especial)

​Padrão 3: Skills + Ferramentas (Expertise E Ações)

​Padrão 4: Skills + MCPs

​Padrão 5: Skills + Apps

​Skills no Nível do Crew

​Formato do SKILL.md

​Campos do Frontmatter

​Estrutura de Diretório

​Skills Pré-carregadas

​Como as Skills São Carregadas

​Skills vs Knowledge

​Perguntas Frequentes