/SKILL.md` no seu repositório. O Devin os descobre automaticamente em todos os seus repositórios conectados. Consulte a [Agent Skills specification](https://agentskills.io/specification) para a referência completa do formato de arquivo.
## Por que as Skills são importantes
Sem Skills, Devin precisa descobrir os fluxos de trabalho do zero em toda sessão. Com Skills, você define um procedimento uma vez, e Devin o segue de forma consistente sempre. Skills são úteis sempre que você tem um fluxo de trabalho que:
* **Deve ser feito da mesma forma sempre** — checklists de teste, etapas de implantação, procedimentos de revisão
* **Exige conhecimento específico do repositório** — quais serviços iniciar, quais portas usar, quais comandos executar
* **Se beneficia de contexto dinâmico** — incorporando diffs do git, nomes de branch ou informações do ambiente no momento da invocação
## Devin Sugere Skills Automaticamente
Devin pode sugerir skills para você automaticamente. Depois que Devin testa sua aplicação ou aprende algo novo sobre sua configuração durante uma sessão, ele sugerirá criar ou atualizar uma skill para capturar esse conhecimento. Você verá uma sugestão na linha do tempo da sua sessão com:
* Um resumo do que foi aprendido (por exemplo, "como iniciar o backend com Docker")
* O conteúdo proposto do arquivo `SKILL.md`
* Um botão **"Criar PR"** para fazer commit da skill no seu repositório
Com o tempo, Devin cria uma biblioteca de skills no seu repositório sobre como executar, testar e implantar sua aplicação.
## Exemplos
### Testes antes de abrir um PR
Uma skill que instrui o Devin sobre como verificar uma aplicação Next.js antes de criar uma pull request:
```markdown theme={null}
---
name: test-before-pr
description: Run the local dev server and verify pages before opening any PR that touches frontend code.
---
## Setup
1. Install dependencies: `npm install`
2. Start the database: `docker-compose up -d postgres`
3. Run migrations: `npx prisma migrate dev`
4. Start the dev server: `npm run dev`
5. Wait for "Ready on http://localhost:3000"
## Verify
1. Read the git diff to identify which pages changed
2. Open each affected page in the browser
3. Check for: console errors, layout issues, broken links
4. Screenshot each page at desktop (1280px) and mobile (375px) widths
## Before Opening the PR
1. Run `npm run lint` and fix any issues
2. Run `npm test` and confirm all tests pass
3. Include screenshots in the PR description
```
### Implantando em um ambiente
Uma skill que implanta o aplicativo usando argumentos para o ambiente de destino, com injeção dinâmica de conteúdo:
```markdown theme={null}
---
name: deploy
description: Deploy the app to a target environment and run smoke tests.
argument-hint:
triggers: ["user"]
---
## Deploy
1. Make sure you are on the correct branch for this deploy
2. Run `./scripts/deploy.sh $0`
3. Wait for the deploy script to complete successfully
## Verify
1. Curl `https://$0.example.com/health` and confirm a 200 response
2. Run the smoke test suite: `npm run test:smoke -- --env=$0`
3. Report the deployment URL and test results
## Current context
- Branch: !`git branch --show-current`
- Last commit: !`git log --oneline -1`
```
Ao invocar com `@skills:deploy staging`, `staging` substitui `$ARGUMENTS` e `$0`, e os blocos `` !`command` `` injetam informações do Git em tempo real. O campo `triggers: ["user"]` garante que o Devin só execute essa skill quando você solicitar explicitamente — ela não será ativada automaticamente.
### Investigando uma parte da base de código
Uma skill para exploração guiada de código que restringe o Devin a ferramentas somente de leitura:
```markdown theme={null}
---
name: investigate
description: Research a part of the codebase and produce a written summary with file references.
allowed-tools: Read, Grep, ListDir
argument-hint:
---
## Research
1. Search the codebase for files related to: $ARGUMENTS
2. Read the most relevant files thoroughly
3. Trace the call chain and data flow
## Summarize
1. Write a summary of how $ARGUMENTS works
2. Include specific file paths and line numbers for every claim
3. Note any concerns, edge cases, or areas that need attention
```
O campo `allowed-tools` restringe o Devin a operações somente de leitura — sem edição, sem comandos de shell. Isso é útil para tarefas de exploração em que você quer análise sem efeitos colaterais.
## Descoberta de Skills
Devin descobre skills a partir de **duas fontes**, que são combinadas no início de cada sessão:
1. **Repositórios indexados** — o back-end do Devin indexa arquivos `SKILL.md` em todos os repositórios conectados à sua organização. Essas skills ficam disponíveis imediatamente quando uma sessão começa, antes de qualquer repositório ser clonado.
2. **Repositórios clonados** — à medida que os repositórios são clonados na máquina usada na sessão, Devin os analisa em busca de arquivos `SKILL.md` em disco. As skills encontradas em disco atualizam ou substituem quaisquer skills indexadas correspondentes desse mesmo repositório, garantindo que Devin use sempre a versão mais recente no branch em que está trabalhando.
Quando a clonagem de um repositório é concluída durante uma sessão, Devin faz automaticamente uma nova varredura nesse repositório para que skills novas ou modificadas sejam detectadas sem necessidade de reiniciar a sessão.
### Locais compatíveis para arquivos de skill
Devin procura por arquivos `SKILL.md` em todos os diretórios a seguir:
* `.agents/skills//SKILL.md` **(recomendado)**
* `.devin/skills//SKILL.md`
* `.github/skills//SKILL.md`
* `.claude/skills//SKILL.md`
* `.cursor/skills//SKILL.md`
* `.codex/skills//SKILL.md`
* `.cognition/skills//SKILL.md`
* `.windsurf/skills//SKILL.md`
Todos os oito caminhos são varridos em cada repositório.
### O que o Devin carrega de um arquivo de skill
Quando uma skill é descoberta, o Devin analisa o **frontmatter** em YAML (o bloco `---` no topo) e extrai:
| Field | Purpose |
| --------------- | -------------------------------------------------------------------------------------------- |
| `name` | Identifica a skill. Usa o nome do diretório pai como padrão se for omitido. |
| `description` | Breve resumo mostrado na lista de skills para que o Devin (e você) saibam o que a skill faz. |
| `allowed-tools` | Restringe quais ferramentas o Devin pode usar enquanto a skill está ativa. |
O Devin também oferece suporte a estes campos adicionais de frontmatter além da especificação padrão:
| Field | Purpose |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `argument-hint` | Texto de ajuda exibido ao lado do nome da skill descrevendo os argumentos esperados. |
| `triggers` | Controla quem pode invocar a skill — `["user", "model"]` por padrão. Defina como `["user"]` para impedir que o Devin a ative automaticamente. |
Tudo **depois** do frontmatter é o corpo da skill — as instruções passo a passo que o Devin deve seguir quando a skill é invocada.
Consulte a [Agent Skills specification](https://agentskills.io/specification) para a referência completa do formato de arquivo.
## Como o Devin Usa Skills
No início de cada sessão, o Devin tem acesso a uma lista de todas as skills disponíveis (nome + descrição). Quando uma skill é **invocada**, o Devin lê o arquivo `SKILL.md` completo e injeta seu conteúdo em seu contexto atual como uma instrução em nível de sistema. Isso significa que o Devin segue ativamente as etapas da skill pelo restante da tarefa — não é apenas uma referência; ela passa a orientar diretamente o comportamento do Devin.
O Devin pode usar skills de várias maneiras:
### Invocação automática
Quando o Devin determina que uma skill é relevante para a tarefa atual, ele a invoca automaticamente. Por exemplo, se você pedir ao Devin para corrigir um bug em código de frontend e existir uma skill `test-before-pr`, o Devin irá ativá-la antes de abrir o PR. Defina `triggers: ["user"]` no frontmatter para impedir a invocação automática de skills que você deseja acionar apenas explicitamente.
### Mencione uma skill no seu prompt
Você pode pedir ao Devin para usar uma skill específica incluindo `@skills:skill-name` na sua mensagem:
```
Fix the login bug on the /auth page @skills:test-before-pr
```
Você também pode passar argumentos:
```
@skills:deploy staging
```
Os argumentos são substituídos no corpo da skill sempre que `$ARGUMENTS`, `$ARGUMENTS[0]`, `$1`, etc. forem encontrados.
### Uma skill ativa de cada vez
Devin só pode ter uma skill ativa de cada vez. Invocar uma nova skill substitui a anterior. Quando uma skill está ativa, Devin é instruído a seguir suas etapas em ordem e concluir cada uma antes de passar para a próxima.
### Pesquisa e listagem
Devin pode pesquisar habilidades por palavra-chave ou diretório se precisar encontrar a mais adequada no meio de uma sessão. Você também pode pedir ao Devin para listar as habilidades disponíveis ou recarregá-las depois de fazer push de alterações em um arquivo de skill.
## Limitações
* **Skills globais / em nível de organização** — Hoje, as skills ficam dentro de repositórios. Para skills em nível de organização, você pode criar um repositório dedicado de "skills" como solução alternativa. Estamos estudando suporte nativo para skills em nível de organização que se apliquem a todos os repositórios.
* **Composição de múltiplas skills** — Atualmente, apenas uma skill pode estar ativa por vez. Estamos trabalhando em suporte para encadear e compor fluxos de trabalho.
## Skills vs. Playbooks
Tanto skills quanto [playbooks](/pt-BR/product-guides/creating-playbooks) fornecem instruções reutilizáveis ao Devin, mas funcionam de maneiras diferentes:
| | Skills | Playbooks |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Where they live** | No seu repositório, como arquivos `SKILL.md` — sob controle de versão junto com o seu código | No aplicativo web do Devin — gerenciados pela interface (UI) |
| **How they're triggered** | O Devin as detecta e executa automaticamente, ou você as referencia com `@skills:name` em qualquer prompt | Anexados manualmente a uma sessão quando você inicia a sessão |
| **Scope** | Com escopo de repositório — o Devin escolhe as skills certas com base em quais repositórios são relevantes para a tarefa | Com escopo de organização — qualquer membro da equipe pode anexar qualquer playbook a qualquer sessão |
| **Auto-suggestion** | O Devin sugere novas skills depois de testar seu app ou aprender algo novo | Criados manualmente pelos membros da equipe |
| **Best for** | Procedimentos de teste, configuração de ambiente local de desenvolvimento, checklists de deploy, fluxos de trabalho específicos do repositório | Modelos de prompt reutilizáveis, padrões de tarefas entre repositórios, guias de onboarding |
**Qual devo usar?** Se suas instruções estiverem vinculadas a um repositório específico — como executá-lo, testá-lo ou fazer o deploy — use uma skill. Se suas instruções forem prompts de uso geral que se aplicam a vários repositórios ou equipes, use um playbook.
## Saiba mais
* [Agent Skills specification](https://agentskills.io/specification) — o padrão aberto para o formato de arquivo `SKILL.md`, campos de frontmatter e estrutura de diretórios
* [Knowledge](/pt-BR/product-guides/knowledge) — para dicas e informações contextuais (não procedimentos passo a passo)
* [Playbooks](/pt-BR/product-guides/creating-playbooks) — para modelos de prompts reutilizáveis associados a sessões