Skills no Claude Code: por que eu vivo no terminal e não em outro lugar
Todo mundo que usa Claude Code hoje já esbarrou em “skills” — mas boa parte só usa o básico (chat, edição de arquivo, um comando aqui e ali). O terminal muda o jogo porque é onde skills, subagents e automação de verdade se conectam sem fricção de UI.
O que é uma skill no Claude Code
- Um pacote de instruções reutilizável que o Claude carrega sob demanda — não é um prompt solto, é algo versionado, específico de projeto ou global.
Primeiro, vamos entender a diferença entre skill, slash command e subagent.
- Skill é simplesmente um arquivo em markdown (*.md) que contém instruções de uma ação ou comportamento. Isso pode ser tratado por projeto ou de forma global. Exemplo: eu tenho uma skill chamada
gitflow-viajafluxque faz com que ele obedeça algumas regras enquanto eu estiver mexendo no código do viajaflux. Por padrão o arquivo fica em.claude/skills/nome-da-sua-skill/SKILL.md.
---
name: gitflow-viajaflux
description: Use ao trabalhar com git no repositório ViajaFlux — criar branch, commitar, abrir PR, fazer merge ou push. Impõe o fluxo de branches (main/beta/feature/hotfix), as convenções de commit e PR com ID do ClickUp, e RECUSA ações proibidas (push direto em main/beta, force-push em branch compartilhada, criar branch fora de beta, abrir PR de feature para main).
---
# Gitflow — ViajaFlux
Fluxo de desenvolvimento oficial do ViajaFlux. Fonte da verdade: doc no Notion
mantido pelo admin (Pablo). Esta skill faz o Claude **seguir e impor** esse fluxo.
## PASSO 0 — Verificar se esta skill se aplica (obrigatório)
Esta skill é global, mas só vale para o repositório **ViajaFlux**. Antes de
aplicar qualquer regra abaixo, confirme que o repo atual é o ViajaFlux:
`bash
git remote -v # o remote (origin) deve apontar para o repositório ViajaFlux
git rev-parse --show-toplevel # o nome da pasta raiz costuma ser "viajaflux"
`
- Se o remote/pasta **for** ViajaFlux → aplique tudo abaixo.
- Se **não for** (ex: loja-maconica, outro projeto) → **não aplique** este fluxo;
esta skill é irrelevante para este repositório. Não imponha nada.
## Estrutura de branches
| Branch | Papel | Nasce de | PR volta para |
|--------------|--------------------------------------|----------|---------------|
| `main` | Produção (protegida) | — | — |
| `beta` | Desenvolvimento principal (protegida)| — | `main` |
| `feature/*` | Funcionalidades | `beta` | `beta` |
| `hotfix/*` | Correções urgentes de produção | `main` | `main` (+ back-merge para `beta`) |
Regra central: **`feature/*` → `beta` → `main`**. Só `beta` e `hotfix/*` podem
fazer merge em `main`.
## Ações que você DEVE recusar
Quando o dev pedir qualquer uma destas, **não execute**. Explique por quê e
ofereça o comando correto do fluxo:
1. **Push direto em `main` ou `beta`** (`git push origin main`/`beta`).
→ Toda mudança entra por PR. Crie uma `feature/*` e abra PR para `beta`.
2. **Force-push em branch compartilhada** (`git push -f` em `main` ou `beta`).
→ Nunca. Reescrever histórico compartilhado quebra o de todo mundo.
3. **Criar branch a partir de `main`** (exceto `hotfix/*`).
→ Features nascem de `beta`. Só hotfix nasce de `main`.
4. **Abrir PR de `feature/*` para `main`.**
→ Feature vai para `beta`. Só `beta` (ou `hotfix/*`) vai para `main`.
5. **Commits gigantes / ficar dias sem commitar.**
→ Commits pequenos e frequentes, todo dia.
Ao recusar, seja breve e útil: diga a regra e mostre o comando certo.
## Convenções obrigatórias de commit e PR
Todo título de commit e de PR inclui o **ID do ClickUp** + **[status]**:
bash
# Commit — "Texto CU-<id>[status]"
git commit -m "Corrige validação de login CU-3h2a9[in progress]"
# PR (título) — mesma convenção
# Implementa autenticação CU-3h2a9[review]
`
Na **descrição do PR**, incluir `it closes #N` (número da issue no GitHub).
Antes de criar branch/PR, lembre o dev de que a issue + branch saem do **ClickUp**.
Histórico **linear**: merge com **squash ou rebase** (nunca merge commit em `beta`/`main`).
## Fluxo de feature (o dia a dia)
`bash
# 1. Atualizar e partir SEMPRE de beta
git fetch --all --prune
git checkout beta
git pull origin beta
# 2. Criar a feature a partir de beta
git checkout -b feature/nome-da-funcionalidade
# 3. Trabalho diário — commits pequenos, com ID + [status]
git add .
git commit -m "feat: adiciona validação de email CU-3h2a9[in progress]"
git push origin feature/nome-da-funcionalidade
# 4. Abrir PR feature/* -> beta (>= 1 aprovação, squash). Descrição: "it closes #N"
# 5. Após merge, sincronizar e limpar
git checkout beta
git pull origin beta
git branch -d feature/nome-da-funcionalidade
`
## Fluxo de hotfix (emergência de produção)
Use **só** quando é realmente urgente e precisa ir direto para produção.
`bash
# 1. Hotfix nasce de main
git checkout main
git pull origin main
git checkout -b hotfix/corrige-bug-critico
# 2. Corrigir e commitar (com ID + [status])
git add .
git commit -m "hotfix: corrige bug crítico X CU-<id>[in progress]"
git push origin hotfix/corrige-bug-critico
# 3. Abrir PR hotfix/* -> main
# 4. Após merge em main, BACK-MERGE para beta (não esquecer!)
git checkout main && git pull origin main
git checkout beta && git pull origin beta
git merge main
git push origin beta
`
## Checklists
**Antes de nova tarefa:** estou em `beta`? fiz `git pull origin beta`? criei a
branch a partir de `beta`?
**Durante:** commits pequenos e frequentes? commitei hoje? mensagens descritivas
com ID + `[status]`? fiz push?
**Ao finalizar a feature:** testes passaram? PR para `beta` (NÃO `main`)? pedi
revisão? respondi aos comentários?
**Hotfix:** é realmente urgente? branch a partir de `main`? PR para `main`?
fiz back-merge `main` → `beta` após o merge?
## Proteções já configuradas no GitHub
`main` só aceita PR de `beta`/`hotfix/*`; `beta` exige aprovação; CI Guard
bloqueia PR inválido para `main`; histórico linear obrigatório; branch precisa
estar sincronizada antes do merge. Se um comando local esbarrar nessas proteções,
não tente contorná-las — o fluxo está sendo aplicado corretamente.Esta é uma skill criada por mim e toda vez que eu falar em git ele vai inteligentemente ler esse arquivo e ver se está de acordo.
Se quiser uma skill para um projeto específico, pode colocar em .claude/ dentro da pasta do projeto. Se quiser de forma global, coloque em ~/.claude.
A skill pode ser feita para gerar um relatório, para proteger ações, para revisar códigos, fazer perguntas…
Slash command
Um slash command é a forma de invocar algo digitando /nome no início da mensagem. É o “gatilho” — o atalho que você digita.
Por exemplo, ao digitar /clear você limpa a sessão e começa do zero. É comum confundir porque é possível você pode invocar uma skill usando /nome-da-skill, mas nem todo comando é uma skill.
- Existem comandos embutidos (built-in) do próprio CLI — como
/help,/clear,/config,/model— que não são Skills; são funções do próprio programa Claude Code.
Sub-agente
Um sub-agente é um trabalhador extra. Em vez de abrir outra aba para trabalhar no mesmo projeto (o que causaria confusão), o sub-agente consegue abrir uma sub-sessão limpa para executar uma tarefa específica dentro do mesmo contexto. Ele funciona de forma isolada em uma nova sessão e devolve o resultado para o agente principal. Literalmente uma delegação de tarefas dentro do mesmo projeto.
É possível inclusive definir especialidades de cada sub-agente. Eu tenho alguns, mas é assunto para outro post.
Por que terminal e não IDE/app
Alguns já sabem, mas eu ou programadores em geral preferem lidar com o Claude no terminal. Isso tem seus motivos: liberdade!
Além de ser mais leve, economizar memória (o que não é um problema para mim hoje), o terminal permite uma maior liberdade ao executar comandos, solicitar tarefas, executar loops, hooks, acessar SSH, provisionar servidores inteiros do zero, etc.
Com o MCP correto configurado é possível solicitar por exemplo para o Claude criar um ambiente na AWS, DigitalOcean (não importa) e subir seu projeto lá. No meio do caminho ele acessa SSH, configura acesso, visita logs, ajusta erros tudo de forma leve, rápida e livre, enquanto eu estou em outra aba trabalhando em outras coisas.
Posso não ter conseguido usar de forma correta o aplicativo, mas quando tentei usar o claude code do aplicativo, ele misturou os worktrees, moveu pastas, criou repositórios git em lugar errado, foi um caos! Pode ter sido eu? Sempre pode. Mas no terminal, nunca passei por isso. Eu sou livre!
Além disso, consigo usar ferramentas que otimizam meu workflow como git, rtk, etc.
O Claude na mão de “não-programadores”
Na corrida da IA, assim como foi a corrida do ouro, todos querem lançar seu projeto rápido e vender rápido. Realmente algumas pessoas vão conseguir fazer isso durante um tempo. Mas sinto em dizer que essa bolha vai estourar tão rápido quanto a ascensão da IA nos próximos meses.
Minha ressalva para alguns devs early-adopter / freelas / ou líderes que acham que conseguem desenvolver um projeto escalável usando o mega-brain e incluindo a diretiva ** não erre! ** achando que terá sucesso com isso:
- Você precisa entender de arquitetura de software;
- Precisa entender sobre segurança: sabe como os dados vazam?;
- Defina qual framework utilizará, qual banco de dados, cache, filas, load balance, proxy, certificado (começou ficar difícil, né?);
- Use Next e Supabase, não tem problema, desde que você saiba os pontos fortes e fracos e se é o melhor para seu tipo de projeto. O Claude é mais treinado e tem menos chances de errar usando esses dois, mas não significa que é a melhor ferramenta para seu projeto SaaS escalável que lhe renderá milhares em recorrência durante muito tempo;
- Aprenda a usar o terminal, é lá que tudo acontece.
Coisas que costumo dizer para alguns amigos: Não exponha tokens em conversas. A chance de em algumas semanas de seu projeto ser invadido, apagado, hackeado, é de 100%. A questão é quanto tempo será necessário para isso acontecer.
O mesmo também não deve ser exposto em headers ou cookies. Proteja-se contra injections.
Enfim, você pode aprender sobre tudo isso e criar skills pra cada tarefa recorrente — elas ajudam a blindar seu código. Não subestime a internet.
Além do mais, pode criar subagentes responsáveis para validar seu código, testar, fazer review, outro para ser o seu experto em UI, UX, TDD, etc.
Aprenda sobre spec-driven
Skills que eu realmente uso no dia a dia
Fui na minha própria pasta ~/.claude/skills (que é só um symlink pro Vault, meu segundo cérebro de novo) pra listar o que eu realmente carrego todo santo dia. Quatro exemplos reais, sem enrolação:
gitflow-viajaflux— já mostrei ela lá em cima. É a única skill que eu escrevi 100% do zero, pensada só pro meu fluxo. Prova que skill não precisa ser genérica pra valer a pena: às vezes o retorno mais alto é blindar uma regra de negócio bem específica sua, que só você (e seu time) vai usar.nextjsereact-best-practices(do plugin oficial da Vercel) — uso direto nos projetos em Next.js do Grupo Fly. Toda vez que mexo num Server Component, Server Action ou reviso um.tsx, essas skills carregam sozinhas e aplicam o padrão certo sem eu precisar lembrar manualmente “ah, não esquece de X”. É terminal + skill funcionando do jeito que devia: eu não abro doc nenhuma, ele já sabe.docx/pdf/pptx(skills oficiais da Anthropic) — uso pra gerar entregável de verdade: resumo de aula do MBA em Word, um relatório, uma apresentação. Em vez de eu formatar manualmente, a skill monta o arquivo do jeito certo e eu só reviso o conteúdo.superpowers— esse é o mais estrutural dos que eu uso. É um conjunto de skills de processo (brainstorming, systematic-debugging, test-driven-development, writing-plans, requesting/receiving-code-review, entre outras) que se auto-impõe: antes de sair implementando qualquer coisa criativa, ele obriga passar por brainstorming; antes de “corrigir” um bug, obriga investigar a causa raiz em vez de sair aplicando patch.
E tem o Maestri — minha squad de agentes (Morpheus, Atlas, Iris, Argos, Themis) pra dividir trabalho de verdade num projeto (arquitetura, backend, frontend, teste, revisão). Sendo bem técnico aqui: Maestri não é uma skill, é uma ferramenta externa que eu chamo pelo terminal (maestri ask); mas ela mora na mesma filosofia de tudo que falei até aqui — nada substitui ter um fluxo repetível em vez de reexplicar contexto toda vez que abro uma sessão.
Minha conclusão
A última coisa que preciso dizer é: Usem skills e CLI CLI -> Command-Line Interface (vulgo Terminal)
É um caminho sem volta e necessário.