Skills

As skills ajudam o Cascade a lidar com tarefas complexas de várias etapas.

As tarefas de engenharia mais difíceis geralmente exigem mais do que apenas bons prompts. Elas podem exigir scripts de referência, templates, checklists e outros arquivos de suporte. As skills permitem agrupar 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 fluxos de trabalho de várias etapas de forma consistente.

O Cascade usa exposição progressiva: por padrão, apenas o name e a description da skill são mostrados ao modelo. O conteúdo completo do SKILL.md e os arquivos de suporte são carregados somente quando o Cascade decide invocar a skill (ou quando você a menciona com @). 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.

​

Como criar uma skill

​

Como usar a UI (mais fácil)

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

​

Criação manual

Skill do workspace (específica do projeto):

1. Crie um diretório: .windsurf/skills/<skill-name>/
2. Adicione um arquivo SKILL.md com frontmatter 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 frontmatter YAML

​

Formato do arquivo SKILL.md

Cada skill exige um arquivo SKILL.md com frontmatter YAML que contém os metadados da skill:

​

Skill de exemplo

---
name: deploy-to-production
description: Guia o processo de implantação em produção com verificações de segurança
---

## Checklist de pré-implantação
1. Execute todos os testes
2. Verifique se há alterações não comitadas
3. Verifique as variáveis de ambiente

## Etapas de implantação
Siga estas etapas para implantar com segurança...

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

​

Campos obrigatórios do frontmatter

• name: Identificador único da skill (exibido na UI e usado em menções com @)
• description: Breve explicação exibida ao modelo para ajudá-lo a decidir quando usar a skill

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

​

Adicionando arquivos de suporte

Coloque os arquivos de suporte na pasta da skill, ao lado de 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

​

Invocação de skills

​

Invocação Automática

Quando sua requisição corresponde à descrição de uma skill, Cascade invoca automaticamente essa skill e usa suas instruções e recursos para concluir a tarefa. Essa é a forma mais comum de usar skills: basta descrever o que você 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.

​

Invocação Manual

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 quer invocar uma skill que talvez não seja acionada automaticamente pela sua requisição.

​

Escopos de skill

Escopo	Localização	Disponibilidade
Workspace	.windsurf/skills/	Apenas no workspace atual. Comitado no seu repo.
Global	~/.codeium/windsurf/skills/	Todos os workspaces na sua máquina. Não comitado.
Sistema (Enterprise)	Específico do SO (veja abaixo)	Todos os workspaces, disponibilizados pela TI. Somente leitura.

Para compatibilidade entre agentes, o Devin Desktop também detecta skills em .agents/skills/ e ~/.agents/skills/. Se você tiver ativado a leitura da configuração do Claude Code, .claude/skills/ e ~/.claude/skills/ também são incluídos na varredura.

​

Skills em nível de sistema (Enterprise)

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:

SO	Caminho
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 nas skills de workspace.

​

Exemplos de casos de uso

​

Fluxo de implantação

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

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

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

​

Procedimentos de teste

Reúna templates de teste, requisitos de cobertura e configurações de CI/CD:

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

​

Práticas recomendadas

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

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

3. 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

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

	Skills	Rules	Workflows
Purpose	Procedimentos com várias etapas e arquivos de suporte	Diretrizes de comportamento (“como se comportar”)	Templates de prompt para tarefas repetíveis
Structure	Pasta com SKILL.md + arquivos de recurso adicionais	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 manualmente 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	Deployments, revisão de código e procedimentos de testing que exigem scripts/templates	Estilo de código, conventions do projeto, restrições	Runbooks pontuais que você aciona explicitamente

Rule of thumb: se o Cascade deve selecioná-lo automaticamente e ele precisa de arquivos de suporte, use uma Skill. Se for uma restrição de comportamento curta, use uma Rule. Se você sempre quiser acioná-lo manualmente, use um Workflow.

​

Documentação relacionada

Se Skills não for o que você está procurando, confira estes outros recursos do Cascade:

• Fluxos de trabalho - Automatize tarefas repetitivas com fluxos de trabalho reutilizáveis em Markdown invocados por comandos de 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 entre conversas com Memories geradas automaticamente e Rules definidas pelo usuário