Ensinei o Claude Code a Gerenciar Minha Infraestrutura com Skills

E se você pudesse ensinar ao Claude Code tudo o que você sabe sobre sua infraestrutura? Não de forma genérica — tipo "como fazer deploy de uma app Laravel" — mas exatamente como VOCÊ faz deploy no SEU servidor, com os SEUS paths, os SEUS serviços, os SEUS SLOs.

É exatamente isso que eu fiz. E coloquei tudo open-source.

O problema: contexto que evapora

O Claude Code é absurdamente capaz. Mas ele não sabe nada sobre o seu servidor. Toda vez que você abre uma sessão nova, precisa explicar de novo: "meu Nginx fica em tal lugar", "meu MySQL tem essas configs", "meu deploy segue esses passos".

Você acaba repetindo o mesmo contexto, sessão após sessão. É como ter um SRE genial que perde a memória toda manhã.

Eu rodo um servidor de produção com 5 apps Laravel, 3 apps Next.js, MySQL, Redis, Supervisor, PM2, Grafana, Loki — o pacote completo. Gerencio tudo via um bot Telegram integrado com o Claude Code. E percebi que o gargalo não era a capacidade da IA, era o contexto.

A solução: Skills — runbooks para IA

Skills são instruções estruturadas que são injetadas no contexto do Claude quando relevantes. Pense nelas como runbooks, mas escritas para serem consumidas por uma IA, não por um humano lendo documentação às 3h da manhã durante um incidente.

Cada skill segue o formato oficial de plugin do marketplace da Anthropic:

plugins/devops/sre/
├── .claude-plugin/
│   └── plugin.json
└── skills/sre/
    └── SKILL.md

O plugin.json define os metadados:

{
  "name": "SRE Server Operations",
  "description": "Full SRE runbook: health checks, SLOs, incident response...",
  "version": "1.0.0"
}

E o SKILL.md é onde mora o conhecimento real — com frontmatter, contexto, comandos, runbooks e boas práticas. É Markdown puro, fácil de escrever, fácil de manter.

Como funciona a seleção automática

Aqui é onde fica interessante. Quando alguém manda uma mensagem pro meu bot Telegram — "verifica se o MySQL tá lento" — o sistema precisa decidir qual skill injetar no contexto.

A abordagem? TF-IDF. NLP clássico. Sem embeddings, sem chamada de API, zero custo.

O sistema tokeniza a query do usuário, calcula a similaridade com a descrição de cada skill, e injeta as mais relevantes. Funciona surpreendentemente bem para esse caso de uso — as descrições das skills são curtas e específicas o suficiente para que TF-IDF dê conta do recado.

Query: "MySQL tá lento, verifica as queries" → Skills injetadas: mysql-performance, sre

Simples, rápido, sem dependência externa.

34 skills em 7 categorias

Organizei tudo em categorias que refletem o dia a dia de quem gerencia infraestrutura:

DevOps (9 skills)

O core. Desde o runbook completo de SRE com SLOs, health checks e resposta a incidentes, até deploy zero-downtime para Laravel e Next.js. Tem skill para troubleshooting de APIs, load balancing com Nginx, profiling de performance, agendamento de crons, diagnóstico de serviços Linux e integração com Cloudflare.

A skill sre sozinha é um manual completo: checklists diários, runbooks para cada tipo de incidente (site fora do ar, MySQL down, Redis cheio, disco cheio, alta CPU), queries Loki úteis, e procedimentos de deploy.

Development (7 skills)

Laravel debugging, desenvolvimento full-stack PHP/Laravel, operações avançadas de Git, e a minha favorita: unfuck-my-git-state. Sério, quantas vezes você ficou com HEAD detached, worktrees fantasma, ou um rebase que deu errado? Essa skill resolve.

Tem também Playwright para testes E2E e GitHub CLI para operações de PR/issues direto do terminal.

Database (4 skills)

mysql-performance é a que mais uso. EXPLAIN analysis, slow query digest, otimização de índices — tudo parametrizado pro meu ambiente. Tem também backup/restore com Cloudflare R2, Redis otimizado para Laravel, e design de schemas SQL.

Monitoring (3 skills)

Grafana alerting, queries LogQL para Loki, e streaming de logs do systemd journal. Cobrem toda a stack de observabilidade.

Marketing (4 skills)

Sim, marketing. meta-ads-advanced tem estratégias de Meta Ads 2026 com Andromeda AI, CAPI server-side, Advantage+. Tem growth hacking, fundamentos de marketing digital, e até scriptwriting para TikTok/Reels virais.

Productivity (5 skills)

agent-memory é especial — memória semântica persistente entre sessões. O Claude esquece tudo quando a sessão acaba, mas com essa skill ele sabe onde e como persistir contexto importante. Tem também Google Workspace, geração de imagens via Gemini, e pesquisa web.

Security (2 skills)

SSH e SSL/TLS. Referência de comandos SSH e gestão de certificados com automação Let's Encrypt.

O poder da especificidade

A diferença entre uma IA genérica e uma IA que conhece seu ambiente é brutal.

Genérico: "Para fazer deploy de uma aplicação Laravel, rode git pull, composer install, php artisan migrate..."

Com skill do seu servidor:

# Deploy zero-downtime - myapp.example.com
cd /home/deploy/myapp.example.com
sudo -u deploy php artisan down --retry=60
sudo -u deploy git pull origin main
sudo -u deploy composer install --no-dev --optimize-autoloader
sudo -u deploy php artisan migrate --force
sudo -u deploy php artisan config:cache
sudo -u deploy php artisan route:cache
sudo -u deploy php artisan view:cache
sudo -u deploy php artisan queue:restart
sudo -u deploy php artisan up
curl -I https://myapp.example.com

O segundo sabe o usuário correto (deploy, não root), sabe quais caches limpar, sabe verificar o health check depois. É a diferença entre conselho genérico e procedimento operacional testado.

Auto-sync: atualiza no GitHub, todos os dispositivos recebem

Um cron simples resolve a distribuição:

# A cada 30 minutos, sync das skills
*/30 * * * * cd /path/to/claude-skills && git pull --quiet

Editou uma skill no GitHub? Em 30 minutos todos os dispositivos que usam o repositório já têm a versão atualizada. Sem deploy, sem CI/CD, sem complicação.

Como criar sua própria skill

É simples. Crie a estrutura de diretórios:

mkdir -p plugins/sua-categoria/sua-skill/.claude-plugin
mkdir -p plugins/sua-categoria/sua-skill/skills/sua-skill

Escreva o plugin.json:

{
  "name": "Minha Skill",
  "description": "O que essa skill faz em uma frase",
  "version": "1.0.0"
}

E o SKILL.md com o conhecimento:

---
name: minha-skill
description: Descrição para matching semântico
---

# Minha Skill

## Contexto
Quando e por que usar essa skill.

## Comandos
Comandos específicos do seu ambiente.

## Runbooks
Procedimentos passo a passo.

## Boas Práticas
O que funciona, o que não funciona.

Pronto. A próxima vez que alguém perguntar algo relacionado, o sistema vai injetar essa skill automaticamente.

Open source

O repositório está público: github.com/billyfranklim1/claude-skills

São 34 skills prontas para usar. Você pode instalar a coleção inteira via marketplace da Anthropic:

/plugin marketplace add billyfranklim1/claude-skills

Ou clonar o repo e adaptar para o seu ambiente. Fork, mude os paths, mude os serviços, mude os SLOs. O formato é o mesmo.

Se você gerencia infraestrutura com Claude Code — ou quer começar — essas skills são um ponto de partida sólido. E se quiser contribuir com skills novas, PRs são bem-vindos.

No fim, a ideia é simples: não repita contexto. Ensine uma vez, use sempre.