Fase 05 · Skills
Skills: workflows sob demanda
Transformar procedimentos repetitivos do time em skills que a IA executa com padrão garantido.
5.1 O que é uma skill
Se o AGENTS.md diz "quem você é", a skill diz "o que você sabe fazer". É carregada sob demanda — só entra no contexto quando a tarefa bate com a descrição dela. Pense em onboarding procedures: como executar tarefas específicas, quando necessário.
- Workflows e procedimentos passo a passo
- O que fazer em situações específicas
- Invocável por comando (ex.:
/deploy,/create-component)
5.2 Estrutura de uma skill
Uma skill é um arquivo Markdown com frontmatter. No mundo da IA, sua stack mais usada é o .md:
.claude/skills/migracao-cronjobs/SKILL.md (Claude Code)
.cursor/skills/migracao-cronjobs/SKILL.md (Cursor)
---
name: migracao-cronjobs
description: Migra @Cron do NestJS para K8s Jobs. Use quando
pedirem para migrar, remover ou padronizar cronjobs.
---
## Passos
1. Busque no repositório todos os decorators @Cron e liste
módulo, service e dependências de cada um.
2. Para cada cronjob, crie `jobs/<nome>.job.ts` que importa o
módulo e chama a função do service (sem refatoração profunda).
3. Remova o decorator @Cron e dependências que ficaram órfãs.
4. Gere o manifesto K8s Job correspondente em `k8s/jobs/`.
## Padrão do arquivo
[exemplo real de um job já migrado, copiado do repositório]A description é o gatilho: é por ela que a IA decide ativar a skill. Escreva nela quando usar, não só o que é.
5.3 Como decidir: AGENTS.md, Skill ou MCP?
Árvore de decisão
- É uma regra/convenção que deve sempre ser seguida? → AGENTS.md
- É um procedimento/workflow executado quando necessário? → Skill
- É uma ferramenta externa (API, serviço, banco) que preciso conectar? → MCP
5.4 Case real: migração de cronjobs
O problema
Escalabilidade · Infra + Arquitetura + Desenvolvimento
Sistemas em NestJS usavam @Cron. Ao escalar replicando pods, as cronjobs
também replicavam — ações duplicadas. A solução desenhada com o time:
remover as @Cron do NestJS, criar um arquivo por cronjob chamando a função
do service, e executar via K8s Jobs. Muitos repositórios, muito trabalho
repetitivo — candidato perfeito para IA.
Onde a IA entrou
Foi criada uma skill que ensinava a IA a: varrer os repositórios atrás das cronjobs existentes e suas dependências, seguir o padrão exato do arquivo de job, e remover as dependências órfãs. Com o padrão definido, a IA executou a migração arquivo por arquivo, de forma padronizada.
A lição
A IA não trouxe a bala de prata — a solução veio da experiência do time com o problema. A IA escalou a execução de uma decisão bem tomada. É essa a divisão de trabalho.
Checklist da fase
Marque cada item ao concluir. O progresso fica salvo neste navegador.