Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Criar uma competência com SKILL.md

Aula 6 de 14 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. Competências: Componentes reutilizáveis
  2. Anatomia de um SKILL.md
  3. Os campos do frontmatter YAML
  4. O corpo do SKILL.md
  5. Criar a sua primeira competência
  6. Boas práticas
  7. Pontos-chave

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.md contendo 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: true torna a competência acessível via um comando de barra (/)
  • Crie competências especializadas com o mínimo de ferramentas necessárias