> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Skills ajudam o Cascade a lidar com tarefas complexas e de múltiplas etapas.

As tarefas de engenharia mais difíceis geralmente exigem mais do que apenas bons prompts. Elas podem precisar de scripts de referência, modelos, checklists e outros arquivos auxiliares. As skills permitem que você reúna tudo isso em pastas que o Cascade pode invocar (ler e usar).

As skills são uma ótima maneira de ensinar o Cascade a executar workflows com várias etapas de forma consistente.

O Cascade usa [**exposição progressiva**](https://agentskills.io/what-are-skills#how-skills-work): apenas o `name` e a `description` da skill são mostrados ao modelo por padrão. O conteúdo completo de `SKILL.md` e os arquivos auxiliares são carregados **somente quando o Cascade decide invocar a skill** (ou quando você faz `@mention` dela). Isso mantém sua janela de contexto enxuta, mesmo com muitas skills definidas.

Para mais detalhes sobre a especificação de Skills, visite [agentskills.io](https://agentskills.io/home).

<div id="how-to-create-a-skill">
  ## Como criar uma skill
</div>

<div id="using-the-ui-easiest">
  ### Usando a interface (método mais fácil)
</div>

1. Abra o painel do Cascade
2. Clique nos três pontos no canto superior direito do painel para abrir o menu **Customizations**
3. Clique na seção `Skills`
4. Clique em `+ Workspace` para criar uma skill de workspace (específica do projeto) ou em `+ Global` para criar uma skill global
5. Dê um nome para a skill (apenas letras minúsculas, números e hífens)

<div id="manual-creation">
  ### Criação manual
</div>

**Skill de workspace (específica do projeto):**

1. Crie um diretório: `.windsurf/skills/<skill-name>/`
2. Adicione um arquivo `SKILL.md` com front matter em YAML

**Skill global (disponível em todos os workspaces):**

1. Crie um diretório: `~/.codeium/windsurf/skills/<skill-name>/`
2. Adicione um arquivo `SKILL.md` com front matter em YAML

<div id="skillmd-file-format">
  ## Formato do arquivo `SKILL.md`
</div>

Cada skill precisa de um arquivo `SKILL.md` com frontmatter YAML contendo os metadados dessa skill:

<div id="example-skill">
  ### Exemplo de skill
</div>

```markdown theme={null}
---
name: deploy-to-production
description: Orienta o processo de deploy para produção com verificações de segurança
---

## Checklist Pré-deploy
1. Executar todos os testes
2. Verificar alterações não commitadas
3. Verificar variáveis de ambiente

## Etapas de Deploy
Siga estas etapas para fazer o deploy com segurança...

[Referencie arquivos de suporte neste diretório conforme necessário]
```

<div id="required-frontmatter-fields">
  ### Campos obrigatórios de frontmatter
</div>

* **name**: Identificador exclusivo da skill (exibido na UI e usado para menções com @)
* **description**: Breve explicação mostrada ao modelo de IA para ajudá-lo a decidir quando invocar a skill

Exemplos de nomes válidos: `deploy-to-staging`, `code-review`, `setup-dev-environment`

<div id="adding-supporting-resources">
  ## Adicionando recursos auxiliares
</div>

Coloque quaisquer arquivos auxiliares na pasta da skill, junto com `SKILL.md`. Esses arquivos ficam disponíveis para o Cascade quando a skill é invocada:

```
.windsurf/skills/deploy-to-production/
├── SKILL.md
├── deployment-checklist.md
├── rollback-procedure.md
└── config-template.yaml
```

<div id="invoking-skills">
  ## Invocando habilidades
</div>

<div id="automatic-invocation">
  ### Invocação automática
</div>

Quando sua solicitação corresponde à descrição de uma skill, Cascade invoca essa skill automaticamente e usa suas instruções e recursos para concluir a tarefa. Este é o modo mais comum de usar skills — você simplesmente descreve o que quer fazer, e Cascade determina quais skills são relevantes.

O campo `description` no frontmatter da sua skill é fundamental: ele ajuda Cascade a entender quando invocar a skill. Escreva descrições que expliquem claramente o que a skill faz e quando ela deve ser usada.

<div id="manual-invocation">
  ### Invocação manual
</div>

Você sempre pode ativar explicitamente uma skill digitando `@skill-name` no campo de entrada do Cascade. Isso é útil quando você quer garantir que uma skill específica seja usada ou quando deseja invocar uma skill que talvez não seja acionada automaticamente pela sua solicitação.

<div id="skill-scopes">
  ## Escopos de Skills
</div>

| Escopo              | Localização                    | Disponibilidade                                           |
| ------------------- | ------------------------------ | --------------------------------------------------------- |
| Workspace           | `.windsurf/skills/`            | Somente workspace atual. Versionado com seu repositório.  |
| Global              | `~/.codeium/windsurf/skills/`  | Todos os workspaces na sua máquina. Não é versionado.     |
| System (Enterprise) | Específico do SO (veja abaixo) | Todos os workspaces, implantado pela TI. Somente leitura. |

<Note>
  Para compatibilidade entre agentes, Windsurf também descobre skills em `.agents/skills/` e `~/.agents/skills/`. Se você tiver habilitado a leitura da configuração do Claude Code, `.claude/skills/` e `~/.claude/skills/` também serão analisados.
</Note>

<div id="system-level-skills-enterprise">
  ### Skills em nível de sistema (Enterprise)
</div>

As organizações Enterprise podem implantar skills que ficam disponíveis em todos os workspaces e não podem ser modificadas pelos usuários finais:

| OS        | Path                                            |
| --------- | ----------------------------------------------- |
| macOS     | `/Library/Application Support/Windsurf/skills/` |
| Linux/WSL | `/etc/windsurf/skills/`                         |
| Windows   | `C:\ProgramData\Windsurf\skills\`               |

Cada skill é um subdiretório que contém um arquivo `SKILL.md`, assim como as skills de workspace.

<div id="example-use-cases">
  ## Exemplos de casos de uso
</div>

<div id="deployment-workflow">
  ### Fluxo de Implantação
</div>

Crie uma skill com scripts de implantação, configurações de ambiente e procedimentos de rollback:

```
.windsurf/skills/deploy-staging/
├── SKILL.md
├── pre-deploy-checks.sh
├── environment-template.env
└── rollback-steps.md
```

<div id="code-review-guidelines">
  ### Diretrizes de revisão de código
</div>

Inclua guias de estilo, listas de verificação de segurança e modelos de revisão:

```
.windsurf/skills/code-review/
├── SKILL.md
├── style-guide.md
├── security-checklist.md
└── review-template.md
```

<div id="testing-procedures">
  ### Procedimentos de Teste
</div>

Modelos de testes de pacote, requisitos de cobertura e configurações de CI/CD:

```
.windsurf/skills/run-tests/
├── SKILL.md
├── test-template.py
├── coverage-config.json
└── ci-workflow.yaml
```

<div id="best-practices">
  ## Boas práticas
</div>

1. **Escreva descrições claras**: A descrição ajuda o Cascade a decidir quando deve invocar a skill. Seja específico sobre o que a skill faz e em quais situações ela deve ser usada.

2. **Inclua recursos relevantes**: Modelos, checklists e exemplos tornam as skills mais úteis. Pense em quais arquivos seriam úteis para alguém concluir a tarefa.

3. **Use nomes descritivos**: `deploy-to-staging` é melhor do que `deploy1`. Os nomes devem indicar claramente o que a skill faz.

<div id="skills-vs-rules-vs-workflows">
  ## Skills vs Rules vs Workflows
</div>

Os três personalizam o Cascade, mas diferem em **estrutura**, **invocação** e **custo de contexto**:

|                       | Skills                                                                        | Rules                                               | Workflows                                        |
| --------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------ |
| **Purpose**           | Procedimentos de várias etapas com arquivos auxiliares                        | Diretrizes comportamentais ("como se comportar")    | Modelos de prompt para tarefas repetíveis        |
| **Structure**         | Pasta com `SKILL.md` + quaisquer arquivos de recurso                          | Um único arquivo `.md` com frontmatter              | Um único arquivo `.md`                           |
| **Invocation**        | O modelo decide (exposição progressiva) ou `@mention`                         | `always_on` / `glob` / `model_decision` / `manual`  | **Somente manual** via `/slash-command`          |
| **In system prompt?** | Não — apenas nome + descrição até ser invocado                                | Depende do modo de ativação                         | Não — listado como comando disponível            |
| **Best for**          | Deploys, revisão de código, procedimentos de teste que exigem scripts/modelos | Estilo de código, convenções do projeto, restrições | Runbooks pontuais que você aciona explicitamente |

**Regra prática:** se o Cascade deve selecioná-lo automaticamente *e* ele precisa de arquivos auxiliares, use um Skill. Se for uma restrição comportamental curta, use uma Rule. Se você sempre quiser acioná-lo manualmente, use um Workflow.

<div id="related-documentation">
  ## Documentação relacionada
</div>

Se Skills não é o que você procura, confira estes outros recursos do Cascade:

* **[Workflows](./workflows)** - Automatize tarefas repetitivas com workflows em Markdown reutilizáveis, acionados por comandos com barra (/)
* **[AGENTS.md](./agents-md)** - Forneça instruções com escopo de diretório que são aplicadas automaticamente com base na localização do arquivo
* **[Memories & Rules](./memories)** - Preserve o contexto ao longo das conversas com memórias geradas automaticamente e regras definidas pelo usuário