Criar uma competência com SKILL.md
Nesta página
Lição atualizada em 2 de novembro de 2026 com base na página Skills da documentação do Vibe: uma competência é um conjunto de instruções (não adiciona ferramentas),
allowed-toolsé lido mas não aplicado, e dois campos foram adicionados (disable-model-invocation,compatibility). Fonte: Skills.
Competências: Componentes reutilizáveis
Os agentes definem quem executa uma tarefa. As competências definem o quê: são conjuntos de instruções reutilizáveis que adicionam procedimentos e comandos de barra (/) ao Mistral Vibe. A distinção torna-se concreta quando a aplica à sua equipa: um agente reflete uma postura de trabalho pessoal, enquanto uma competência encapsula um procedimento que todos devem executar da mesma forma.
Uma competência é um diretório contendo um ficheiro SKILL.md com um frontmatter YAML. Esta estrutura segue a especificação aberta Agent Skills, tornando as competências portáteis e partilháveis: a mesma pasta funciona na máquina do seu colega sem adaptação.
Anatomia de um SKILL.md
Eis a estrutura completa de uma competência, ilustrada por um exemplo de revisão de código automatizada:
---
name: code-review
description: Performs automated code reviews with quality analysis
license: MIT
user-invocable: true
allowed-tools:
- read_file
- grep
- ask_user_question
---
# Code Review Skill
This skill analyzes source code quality by checking:
1. **Naming conventions** — variables, functions, classes
2. **Cyclomatic complexity** — functions that are too long or nested
3. **Duplication** — copy-pasted code to refactor
4. **Security** — dangerous patterns (eval, SQL injection, XSS)
## Usage
Run `/code-review` followed by the path or description of the code to analyze.
## Output format
The report is structured in three levels:
- 🔴 **Critical** — fix immediately
- 🟡 **Warning** — fix before merging
- 🟢 **Suggestion** — optional improvement
Os campos do frontmatter YAML
O campo name é o identificador único da competência. É utilizado para ativar, desativar e referenciar a competência nas configurações. Este nome torna-se também o comando de barra (/), pelo que vale a pena mantê-lo curto.
name: code-review
O description, até 1.024 caracteres, é a frase que aparece quando o Vibe lista as competências disponíveis. Escreva-o da perspetiva de quem procura: deve permitir escolher entre duas competências semelhantes sem abrir os ficheiros.
description: Performs automated code reviews with quality analysis
O campo license indica a licença da competência, o que se torna importante assim que a partilha para além da sua própria estação de trabalho.
license: MIT
O booleano user-invocable, verdadeiro por predefinição, expõe a competência como um comando de barra (/). Defina-o como false para a ocultar do menu /: o agente pode ainda assim carregá-la automaticamente quando a tarefa for adequada.
user-invocable: true # Acessível via /code-review
user-invocable: false # Oculto do menu /, o agente pode ainda carregá-la
O campo disable-model-invocation, quando definido como true, impede que o agente carregue a competência por iniciativa própria: só é executada se digitar /skill-name. Reserve isto para procedimentos que nenhum modelo deve acionar sem o seu consentimento explícito, como uma implementação.
disable-model-invocation: true
Dois campos informativos completam a lista: compatibility, que nota os pré-requisitos (“Requires git”), e allowed-tools, que lista as ferramentas que a competência pretende utilizar. Tenha cuidado com este último: a documentação especifica que o Vibe o lê mas não o aplica. Uma competência pode chamar qualquer ferramenta que o agente ativo autorize. Para limitar o que uma competência pode fazer, restrinja as ferramentas e permissões do agente (Lições 2 e 3).
allowed-tools:
- read_file
- grep
- ask_user_question
O corpo do SKILL.md
Após o frontmatter, o corpo do ficheiro é Markdown de formato livre. Serve simultaneamente como documentação e prompt: o Vibe lê-o para compreender como funciona a competência e em que contexto a deve aplicar. É aqui que descreve o que a competência faz, os passos do seu funcionamento, o formato de saída esperado e exemplos de utilização. Um corpo vago produz uma competência imprevisível; um corpo preciso produz uma competência que gera o mesmo resultado semana após semana.
Criar a sua primeira competência
Vamos construir uma competência de geração de testes. Comece por criar o seu diretório:
mkdir -p ~/.vibe/skills/test-generator
Coloque o seguinte SKILL.md lá dentro. Repare como o corpo responde a perguntas que o Vibe teria de adivinhar: qual a estrutura a escolher, como nomear os blocos, onde escrever o ficheiro de saída.
---
name: test-generator
description: Generates unit tests for TypeScript/JavaScript functions
license: MIT
user-invocable: true
allowed-tools:
- read_file
- write_file
- grep
---
# Test Generator
Generates comprehensive unit tests for
TypeScript and JavaScript functions.
## Process
1. Read the target source file
2. Identify all exported functions
3. For each function, generate:
- Happy path test
- Test with empty/null inputs
- Edge case tests
- Expected error tests
4. Write tests to an adjacent `.test.ts` file
## Conventions
- Framework: Vitest (default) or Jest if detected
- Naming: `describe` per function, `it` per test case
- Assertions: `expect` with precise matchers
- No mocks unless necessary (external dependencies)
## Example
For a file `utils/math.ts` containing `add(a, b)`,
the skill generates `utils/math.test.ts` with corresponding tests.
Assim que o ficheiro é criado, a competência fica imediatamente disponível: sem comando de instalação, sem reinício. Inicie o Vibe e chame-a num ficheiro real.
vibe
# > /test-generator src/utils/math.ts
O Vibe carrega a competência, lê o seu SKILL.md para compreender o comportamento esperado e executa a tarefa com as ferramentas autorizadas. Dedique tempo a ler o resultado: ao comparar a saída com o que imaginou, refinara o corpo do ficheiro.
Boas práticas
Mantenha uma competência por funcionalidade. Misturar revisão de código e geração de testes num único ficheiro produz um prompt hesitante e impede-o de desativar um sem perder o outro. Da mesma forma, limite as ferramentas autorizadas às que a competência realmente necessita.
O resto depende da qualidade da escrita. O corpo do SKILL.md é o seu prompt: seja preciso e inclua exemplos concretos do que a competência produz — um exemplo de saída vale mais do que três linhas de descrição. Por fim, teste a sua competência em vários casos, incluindo um difícil, antes de a partilhar com a equipa.
Pontos-chave
- Uma competência é um diretório com um ficheiro
SKILL.mdcontendo um frontmatter YAML - O frontmatter define o nome, descrição, ferramentas permitidas e invocabilidade
- O corpo em Markdown serve simultaneamente como documentação e prompt para o Vibe
user-invocable: truetorna a competência acessível via um comando de barra (/)- Crie competências especializadas com o mínimo de ferramentas necessárias