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: 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.
Usando a interface (método mais fácil)
- Abra o painel do Cascade
- Clique nos três pontos no canto superior direito do painel para abrir o menu Customizations
- Clique na seção
Skills
- Clique em
+ Workspace para criar uma skill de workspace (específica do projeto) ou em + Global para criar uma skill global
- Dê um nome para a skill (apenas letras minúsculas, números e hífens)
Skill de workspace (específica do projeto):
- Crie um diretório:
.windsurf/skills/<skill-name>/
- Adicione um arquivo
SKILL.md com front matter em YAML
Skill global (disponível em todos os workspaces):
- Crie um diretório:
~/.codeium/windsurf/skills/<skill-name>/
- Adicione um arquivo
SKILL.md com front matter em YAML
Cada skill precisa de um arquivo SKILL.md com frontmatter YAML contendo os metadados dessa skill:
---
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]
Campos obrigatórios de frontmatter
- 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
Adicionando recursos auxiliares
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
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.
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.
| 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. |
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.
Skills em nível de sistema (Enterprise)
| OS | Path |
|---|
| macOS | /Library/Application Support/Windsurf/skills/ |
| Linux/WSL | /etc/windsurf/skills/ |
| Windows | C:\ProgramData\Windsurf\skills\ |
SKILL.md, assim como as skills de workspace.
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
Diretrizes de revisão de código
.windsurf/skills/code-review/
├── SKILL.md
├── style-guide.md
├── security-checklist.md
└── review-template.md
.windsurf/skills/run-tests/
├── SKILL.md
├── test-template.py
├── coverage-config.json
└── ci-workflow.yaml
-
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.
-
Inclua recursos relevantes: Modelos, checklists e exemplos tornam as skills mais úteis. Pense em quais arquivos seriam úteis para alguém concluir a tarefa.
-
Use nomes descritivos:
deploy-to-staging é melhor do que deploy1. Os nomes devem indicar claramente o que a skill faz.
Skills vs Rules vs Workflows
| 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 |
- Workflows - Automatize tarefas repetitivas com workflows em Markdown reutilizáveis, acionados por comandos com barra (/)
- 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 - Preserve o contexto ao longo das conversas com memórias geradas automaticamente e regras definidas pelo usuário
