Skills

Ensine o Devin a executar procedimentos reutilizáveis fazendo commit de arquivos SKILL.md nos seus repositórios

​

O que são Skills?

Skills são arquivos SKILL.md que você adiciona aos seus repositórios e que ensinam o Devin a executar procedimentos reutilizáveis — qualquer fluxo de trabalho repetível que você queira que o Devin siga de forma consistente. Testar seu app antes de abrir um PR, fazer deploy em um ambiente, investigar uma base de código, criar a estrutura inicial de um novo serviço — se você conseguir escrever isso como instruções passo a passo, poderá transformar isso em uma skill.

Elas seguem o padrão aberto Agent Skills standard, então os mesmos arquivos de skill funcionam em várias ferramentas de programação com IA.

Coloque os arquivos de skill em .agents/skills/<skill-name>/SKILL.md no seu repositório. O Devin os descobre automaticamente em todos os seus repositórios conectados. Consulte a Agent Skills 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:

---
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:

---
name: deploy
description: Deploy the app to a target environment and run smoke tests.
argument-hint: <environment>
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:

---
name: investigate
description: Research a part of the codebase and produce a written summary with file references.
allowed-tools: Read, Grep, ListDir
argument-hint: <topic or area to investigate>
---

## 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-name>/SKILL.md (recomendado)
• .github/skills/<skill-name>/SKILL.md
• .claude/skills/<skill-name>/SKILL.md
• .cursor/skills/<skill-name>/SKILL.md
• .codex/skills/<skill-name>/SKILL.md
• .cognition/skills/<skill-name>/SKILL.md
• .windsurf/skills/<skill-name>/SKILL.md

Todos os sete 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 para a referência completa do formato de arquivo.

​

Conteúdo dinâmico

Além da especificação padrão, o Devin oferece suporte a dois tipos de conteúdo dinâmico no corpo da skill que são processados no momento da invocação:

• $ARGUMENTS — substituído pela string completa de argumentos passada quando a skill é invocada (por exemplo, via @skills:deploy staging prod). Você também pode acessar argumentos individuais por índice: $ARGUMENTS[0] ou $0 para o primeiro, $ARGUMENTS[1] ou $1 para o segundo, etc. Os argumentos são separados por espaço em branco.
• !`command` — o comando é executado na raiz do repositório e substituído pela sua saída padrão (stdout), permitindo que as skills incluam valores dinâmicos como nomes de branch ou números de porta.

​

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 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 — o padrão aberto para o formato de arquivo SKILL.md, campos de frontmatter e estrutura de diretórios
• Knowledge — para dicas e informações contextuais (não procedimentos passo a passo)
• Playbooks — para modelos de prompts reutilizáveis associados a sessões