Skills

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.

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.