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.

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 uma Skill com a CLI

A CLI é a forma suportada de criar uma skill — ela gera a estrutura de diretórios e um SKILL.md válido para você:

Terminal

crewai skill create code-review

Dentro de um projeto de crew (onde o pyproject.toml está) isso cria ./skills/code-review/; fora de um projeto, cria ./code-review/ no diretório atual (você pode forçar esse comportamento com --no-project):

skills/
└── code-review/
    ├── SKILL.md          # Obrigatório — instruções (template pré-preenchido)
    ├── references/       # Opcional — documentos de referência
    ├── scripts/          # Opcional — scripts executáveis
    └── assets/           # Opcional — arquivos estáticos

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
)

Criando, Publicando e Instalando Skills

Skills têm um ciclo de vida completo gerenciado pela CLI: crie-as com crewai skill create, publique-as com crewai skill publish — criar diretórios à mão funciona para experimentos locais, mas a CLI é o fluxo de trabalho pretendido e mantém a estrutura e o frontmatter da sua skill válidos.

Criar

Terminal

crewai skill create my-skill

Gera o diretório (em ./skills/ dentro de um projeto de crew) com um SKILL.md de template, além dos diretórios vazios scripts/, references/ e assets/. Edite o SKILL.md para definir as instruções.

Publicar

Execute de dentro do diretório da skill (onde o SKILL.md está):

Terminal

cd skills/my-skill
crewai skill publish

A publicação lê name, description e metadata.version do frontmatter do SKILL.md e envia a skill para o registro da CrewAI. Skills publicadas são sempre escopadas à sua organização — assim como ferramentas, apenas membros da organização que publicou podem vê-las e instalá-las; não há visibilidade pública. Flags úteis:

Flag	Efeito
`--org <slug>`	Publica sob uma organização específica (sobrepõe as configurações).
`--force`	Pula a validação de estado do git (alterações não commitadas, etc.).

Instalar

Instale uma skill publicada pela sua referência @org-uuid/name:

Terminal

crewai skill install @your-org-uuid/code-review

Use o UUID da sua organização, não o nome — nomes de organização não são únicos, então um nome pode resolver para a organização errada e a instalação falha com um erro de “não encontrado”. Execute crewai org list para ver o UUID (a coluna ID) de cada organização à qual você pertence.

Dentro de um projeto de crew, a skill é colocada em ./skills/{name}/; fora de um projeto, vai para o cache compartilhado em ~/.crewai/skills/{org-uuid}/{name}/. Agentes também podem referenciar skills do registro diretamente — elas são resolvidas a partir do cache local (ou do diretório skills/ do projeto) em tempo de execução:

agent = Agent(
    role="Senior Code Reviewer",
    goal="Review pull requests for quality and security issues",
    backstory="Staff engineer with expertise in secure coding practices.",
    skills=["@your-org-uuid/code-review"],  # registry ref, resolved locally
)

Buscar

Lista as skills publicadas na sua organização no AMP, opcionalmente filtradas por um termo comparado ao handle e à descrição de cada skill:

Terminal

crewai skill search
crewai skill search "code review"

Cada linha começa com o status da verificação de segurança da versão mais recente (passed, pending ou failed; só uma versão passed é instalada), seguido de <handle>@<latest-version> e da descrição. Um handle ou versão com caracteres que uma referência não pode conter aparece entre aspas. Uma linha acima das skills traz o UUID da organização atual na referência que o skills de um agente aceita, @<org-uuid>/<handle>@<version>; o crewai skill install aceita @<org-uuid>/<handle>. Defina a organização antes com crewai org switch <org-uuid>. Uma skill marcada com (public) pode pertencer a outra organização, cujo UUID a referência dela exige; a lista não o mostra.

Listar

Terminal

crewai skill list

Mostra as skills instaladas tanto do diretório ./skills/ do projeto quanto do cache global, com suas versões e caminhos.

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.

Começando

Guias

Conceitos-Chave

Integração MCP

Ferramentas

Observabilidade

Aprenda

Telemetria

Visão Geral

Início Rápido

1. Crie uma Skill com a CLI

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

Criando, Publicando e Instalando Skills

Criar

Publicar

Instalar

Buscar

Listar

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

​Visão Geral

​Início Rápido

​1. Crie uma Skill com a CLI

​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

​Criando, Publicando e Instalando Skills

​Criar

​Publicar

​Instalar

​Buscar

​Listar

​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

Visão Geral

Início Rápido

1. Crie uma Skill com a CLI

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

Criando, Publicando e Instalando Skills

Criar

Publicar

Instalar

Buscar

Listar

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