Criando Skills

As skills são definidas em arquivos SKILL.md dentro de um diretório nomeado. Esta página explica tudo o que você precisa saber para escrever skills eficazes.

Estrutura de Arquivos

Coloque as skills no diretório apropriado, de acordo com o escopo:

# Específico do projeto (com commit no git)
.devin/skills/
└── my-skill/
    └── SKILL.md

# Global — disponível em todos os projetos (sem commit)
# Linux/macOS:
~/.config/devin/skills/
└── my-skill/
    └── SKILL.md

# Windows:
%APPDATA%\devin\skills\
└── my-skill\
    └── SKILL.md

O nome do diretório é o identificador da skill (usado na chamada /my-skill). O arquivo SKILL.md contém frontmatter YAML opcional e o conteúdo do prompt da skill.

No Windows, %APPDATA% normalmente corresponde a C:\Users\<YourUser>\AppData\Roaming.

Referência do frontmatter

---
name: my-skill
description: What this skill does (shown in completions)
argument-hint: "[file] [options]"
model: sonnet
allowed-tools:
  - read
  - grep
  - glob
  - exec
permissions:
  allow:
    - Read(src/**)
  deny:
    - exec
  ask:
    - Write(**)
triggers:
  - user
  - model
---

Your prompt content goes here...

Todos os campos do frontmatter

Campo	Tipo	Padrão	Descrição
`name`	string	nome do diretório	Nome de exibição da skill
`description`	string	nenhum	Exibido nas sugestões de autocompletar do comando de barra
`argument-hint`	string	nenhum	Dica exibida após o nome do comando (ex.: `[filename]`)
`model`	string	modelo atual	Substitui o modelo usado ao executar esta skill
`subagent`	boolean	`false`	Executa a skill como um subagente em vez de inline
`agent`	string	nenhum	Executa a skill como um subagente usando um perfil específico de subagente personalizado
`allowed-tools`	list	nenhum	Ferramentas aprovadas automaticamente (sem prompt de permissão) enquanto a skill é executada. Não restringe a disponibilidade das ferramentas — consulte Ferramentas aprovadas automaticamente. Não se aplica quando a skill é executada como subagente
`permissions`	object	herdar	Substituições de permissão para esta skill. Não se aplica quando a skill é executada como subagente
`triggers`	list	`[user, model]`	Como a skill pode ser acionada

Override de modelo

Use o campo model para executar uma skill usando um modelo diferente do que está ativo na sessão atual. Isso é útil para usar um modelo mais rápido em tarefas simples ou um modelo mais avançado em tarefas complexas:

---
name: quick-fix
description: Fast lint fix using a lightweight model
model: swe
---

Fix the lint errors in the current file.

O nome do modelo usa os mesmos valores da flag --model da CLI (por exemplo, opus, sonnet, swe, codex). Consulte Models para ver a lista completa.

Executando Skills como Subagentes

Executar skills como subagentes é experimental. Os campos subagent e agent do frontmatter podem mudar em versões futuras.

Por padrão, o prompt de uma skill é injetado na conversa atual — o agente o processa inline. Como alternativa, você pode executar uma skill como um subagente, o que inicia um worker independente com sua própria janela de contexto. Isso é útil para skills que executam tarefas focadas e autocontidas, em que você não quer que a saída sobrecarregue a conversa principal. Há duas maneiras de executar uma skill como subagente:

`subagent: true`

Defina subagent: true para executar a skill como subagente usando o perfil padrão subagent_general:

---
name: deep-research
description: Thorough codebase research on a topic
subagent: true
model: sonnet
---

Research the topic the user asked about thoroughly.

Search broadly, follow references, and trace call chains.
Report all findings with specific file paths and line numbers.

Ao ser invocada, esta skill inicia um subagente em primeiro plano que executa o prompt da skill como tarefa. O agente principal aguarda a conclusão do subagente e, em seguida, lê e resume os resultados.

Quando uma skill é executada como subagente, seus campos de frontmatter allowed-tools e permissions não são aplicados. O subagente é executado com o conjunto de ferramentas do seu perfil — subagent_general tem acesso a todas as ferramentas. Para limitar quais ferramentas uma skill de subagente pode usar, defina um perfil de subagente personalizado com allowed-tools e referencie-o com agent: em vez de subagent: true.

`agent: <profile>`

Use o campo agent para executar a skill como um subagente com um perfil de subagente personalizado específico:

---
name: review-pr
description: Review the current PR using the reviewer subagent
agent: reviewer
---

Review the staged changes for correctness, security, and style issues.

O valor agent deve corresponder ao nome de um perfil de subagente registrado (seja um perfil integrado, como subagent_explore / subagent_general, ou um perfil personalizado que você definiu). O subagente herda o prompt de sistema, as restrições de ferramentas e o modelo do perfil — enquanto o conteúdo da skill se torna a task. O allowed-tools de um perfil personalizado é uma restrição real (ferramentas não listadas ficam indisponíveis para o subagente), então essa é a forma de executar uma skill com um conjunto limitado de ferramentas.

Se agent e subagent estiverem definidos, agent terá precedência. O campo model na skill faz override do modelo do perfil do subagente quando ambos estiverem especificados.

Skills executadas como subagentes não criam subagentes aninhados — se a skill já estiver sendo executada dentro de um subagente, ela será executada inline para evitar recursão infinita.

Orquestrando subagentes com skills

Como as skills podem ser executadas como subagentes, você pode usá-las para orquestrar trabalhos em várias etapas. Defina um conjunto de skills de subagente, cada uma responsável por uma tarefa específica, e depois escreva uma skill comum que as invoque. A skill externa se torna a orquestradora — ela chama cada subagente, coleta os resultados e decide o que fazer em seguida. Por exemplo, aqui estão duas skills de subagente e uma orquestradora que as coordena:

---
name: research-changes
description: Research recent code changes and their impact
subagent: true
---

Analyze the recent changes in this repository:

1. Run `git log --oneline -20` to see recent commits
2. For each significant commit, examine what changed and why
3. Identify any patterns, risks, or areas that need attention

Report your findings with specific file paths and commit references.

---
name: validate-tests
description: Run tests and validate coverage for recent changes
subagent: true
---

Validate the test suite for the project:

1. Identify the test framework and run command
2. Run the full test suite
3. Check for any failing tests
4. Review test coverage for recently changed files

Report which tests pass, which fail, and any coverage gaps.

---
name: health-check
description: Full project health check — research changes then validate tests
---

Perform a full health check on this project:

1. First, use the /research-changes skill to understand recent changes
2. Then, use the /validate-tests skill to verify the test suite
3. Finally, synthesize the findings from both into a summary:
   - What changed recently and why
   - Whether tests are passing
   - Any risks or recommended actions

Invocar /health-check executa o orquestrador no agente principal. Ele chama /research-changes, que cria um subagente para explorar o repo. Quando isso termina, ele chama /validate-tests, que cria outro subagente para executar os testes. Em seguida, o orquestrador combina os dois resultados em um resumo final. Uma skill de subagente nunca usará um subagente ao chamar outras skills, mesmo que essas skills tenham subagent: true — elas são executadas inline. Isso significa que você não precisa se preocupar com aninhamento sem limites. O padrão de orquestração tem sempre apenas um nível de profundidade: o orquestrador cria subagentes, e esses subagentes executam todo o restante inline.

Conteúdo do prompt

O conteúdo do arquivo SKILL.md (após o frontmatter) é o prompt injetado quando a skill é invocada.

Permissões

As skills podem definir seu próprio escopo de permissões usando a mesma sintaxe da configuração principal de permissões:

permissions:
  allow:
    - Read(src/**)
    - Exec(npm run test)
  deny:
    - Write(/etc/**)
    - exec
  ask:
    - Write(src/**)

Como as permissões de skill funcionam:

allow — Esses escopos são aprovados automaticamente durante a execução da skill
deny — Esses escopos são bloqueados durante a execução da skill
ask — Esses escopos sempre pedem confirmação ao usuário

deny é a forma de bloquear totalmente uma ferramenta em uma skill inline. Entradas com nome de ferramenta, como exec ou edit, bloqueiam a ferramenta inteira, e padrões mcp__server__tool bloqueiam ferramentas MCP — veja Permissões Baseadas em Ferramentas.

As permissões de skill são adicionadas às permissões base da sessão (não as substituem). Uma skill não pode conceder permissões negadas em um nível mais alto (configuração do projeto ou da organização).

As permissões de skill se aplicam apenas quando a skill é executada inline. Elas não são aplicadas quando a skill é executada como subagente (subagent: true ou agent:).

Ferramentas aprovadas automaticamente

allowed-tools lista as ferramentas aprovadas automaticamente durante a execução da skill, para que o agente possa usá-las sem um prompt de permissão:

allowed-tools:
  - read
  - grep
  - glob

Cada entrada equivale a uma entrada de permissions.allow para esse nome de ferramenta. Nomes de ferramentas disponíveis: read, edit, grep, glob, exec Você também pode aprovar automaticamente ferramentas MCP:

allowed-tools:
  - read
  - mcp__github__list_issues
  - mcp__github__create_issue

allowed-tools não é uma restrição. As ferramentas que não estiverem listadas continuam disponíveis para a skill e passam pelas verificações normais de permissão (solicitando confirmação ao usuário ou executando sem confirmação, caso as permissões da sessão já as permitam). Omitir allowed-tools não muda em nada quais ferramentas a skill pode usar — significa apenas que nenhuma ferramenta está pré-aprovada.Para de fato impedir que uma skill use uma ferramenta:

Em skills inline, adicione o nome da ferramenta em permissions.deny (consulte Permissões).
Em skills executadas como subagente, defina um perfil de subagente personalizado com allowed-tools e execute a skill com agent: <profile>. Em um perfil de subagente, allowed-tools restringe o conjunto de ferramentas; em uma skill, não.

Exemplos

Skill de revisão de código

---
name: review
description: Review staged changes for issues
allowed-tools:
  - read
  - grep
  - glob
  - exec
permissions:
  allow:
    - Exec(git diff)
    - Exec(git log)
---

Run `git diff --staged` and review the changes for quality issues.

Evaluate:
1. **Correctness** — Any logic errors or edge cases?
2. **Security** — Any vulnerabilities introduced?
3. **Performance** — Any obvious inefficiencies?
4. **Style** — Consistent with the codebase?

Provide a summary with specific line references.

Gerador de Componentes

---
name: component
description: Generate a React component from a description
argument-hint: "<ComponentName>"
allowed-tools:
  - read
  - edit
  - grep
  - glob
model: sonnet
permissions:
  allow:
    - Write(src/components/**)
---

Crie um novo componente React usando o nome fornecido pelo usuário:

1. Verifique os componentes existentes em src/components/ para convenções de estilo
2. Crie o arquivo do componente em src/components/<ComponentName>/<ComponentName>.tsx
3. Crie uma exportação barrel em src/components/<ComponentName>/index.ts
4. Adicione testes básicos em src/components/<ComponentName>/<ComponentName>.test.tsx
5. Siga os padrões encontrados nos componentes existentes

Checklist de implantação

---
name: deploy
description: Run through the deployment checklist
triggers:
  - user
allowed-tools:
  - read
  - exec
  - grep
permissions:
  allow:
    - Exec(npm run)
    - Exec(git)
---

Run through the deployment checklist:

1. Run the test suite: `npm run test`
2. Run the linter: `npm run lint`
3. Check for uncommitted changes: `git status`
4. Verify the build: `npm run build`
5. Show the current branch and last commit

Report the status of each step. If anything fails, stop and explain the issue.

Especialista em buscas

---
name: find
description: Find relevant code across the project
argument-hint: "<what to find>"
allowed-tools:
  - read
  - grep
  - glob
triggers:
  - user
  - model
---

Pesquise o código-fonte minuciosamente para o que o usuário perguntou.

Use grep para busca de conteúdo e glob para descoberta de arquivos.
Forneça caminhos de arquivos relevantes e trechos de código.
Explique como as partes se conectam.

Dicas

Mantenha os prompts focados

Uma skill deve fazer bem uma única coisa. Crie várias skills em vez de uma mega-skill.

Inclua exemplos

Mostre ao agente, no prompt, como é uma boa saída.

Negue o que uma skill não deve fazer

Use permissions.deny (ou um perfil de subagente personalizado) para bloquear ferramentas. allowed-tools apenas pula prompts.

Teste com /skill-name

Invoque sua skill e refine o prompt até que a saída seja o que você quer.

Primeiros passos

Integrações do Editor

Extensibilidade

Enterprise

Referência

Changelog

Estrutura de Arquivos

Referência do frontmatter

Todos os campos do frontmatter

Override de modelo

Executando Skills como Subagentes

`subagent: true`

`agent: <profile>`

Orquestrando subagentes com skills

Conteúdo do prompt

Permissões

Ferramentas aprovadas automaticamente

Exemplos

Skill de revisão de código

Gerador de Componentes

Checklist de implantação

Especialista em buscas

Dicas

Mantenha os prompts focados

Inclua exemplos

Negue o que uma skill não deve fazer

Teste com /skill-name

​Estrutura de Arquivos

​Referência do frontmatter

​Todos os campos do frontmatter

​Override de modelo

​Executando Skills como Subagentes

​subagent: true

​agent: <profile>

​Orquestrando subagentes com skills

​Conteúdo do prompt

​Permissões

​Ferramentas aprovadas automaticamente

​Exemplos

​Skill de revisão de código

​Gerador de Componentes

​Checklist de implantação

​Especialista em buscas

​Dicas

Mantenha os prompts focados

Inclua exemplos

Negue o que uma skill não deve fazer

Teste com /skill-name

Estrutura de Arquivos

Referência do frontmatter

Todos os campos do frontmatter

Override de modelo

Executando Skills como Subagentes

`subagent: true`

`agent: <profile>`

Orquestrando subagentes com skills

Conteúdo do prompt

Permissões

Ferramentas aprovadas automaticamente

Exemplos

Skill de revisão de código

Gerador de Componentes

Checklist de implantação

Especialista em buscas

Dicas