convez.ai
SkillDevOps & InfraestruturaIntermediário
tensorshift

Claude Nginx Skill

tensorshift/claude-nginx-skill

Expert em nginx para Claude: author, review, harden e debug configs com diagnóstico inteligente

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill de produção para Claude especializada em nginx — escreve, revisa, fortalece e debugga configurações nginx com diagnóstico baseado em logs. Aborda armadilhas reais de operação (MTU, VPN, headers perdidos, rate limiting) que respostas genéricas costumam perder.

Instalação

$npx convez-ai tensorshift/claude-nginx-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Criar e revisar configurações nginx do zero para produção
  • Diagnosticar problemas de conectividade a partir de logs antes de fazer mudanças
  • Configurar reverse proxy com WebSocket, TLS/SSL, HTTP/2 e HTTP/3
  • Hardening de segurança: headers, rate limiting, tuning de TLS, OCSP
  • Resolver falhas em mobile/redes lossy e assimetria VPN/DPI

Veredito

Skill robusto e operacionalmente inteligente — vai além de snippets genéricos e codifica lições reais de produção (MTU, DPI, headers herdados, anti-patterns). Estrutura com progressive disclosure torna-o acessível. Essencial para times que precisam de nginx expertise integrada ao Claude.

README

A tradução para o português deste README ainda está na fila.

claude-nginx-skill

A deep, production-grade Claude Agent Skill for working with nginx — a full-spectrum assistant for authoring, configuring, reviewing, hardening, and debugging configs. It turns Claude (in Claude Code, the Claude apps, or the Agent SDK) into a version-aware nginx expert: it writes correct configs from scratch for everyday tasks, and when something breaks it diagnoses from logs before changing anything instead of pasting generic snippets.

Everyday tasks it handles (not just incidents): new site / virtual host, reverse proxy with WebSockets, TLS/SSL + HTTP/2 + HTTP/3, SPA/Next.js & S3/MinIO proxying, load balancing & upstreams, caching, gzip/brotli, rate limiting, and security headers — see the reference files below.

On top of the standard best practices, it encodes real operational lessons that generic answers miss:

  • 📉 Mobile / lossy-network failures — Path-MTU black holes, per-request TLS overhead, "loads on desktop, infinite spinner on mobile."
  • 🛰️ VPN asymmetry & DPI — "works through a foreign VPN but not directly" (and the reverse): how to tell a server problem from a network/DPI/blocklist problem in one minute.
  • 🕳️ Silent config traps — add_header inheritance dropping your security headers, Last-Modified $date_gmt killing cache, if-is-evil, duplicate server blocks, the HTTP/2 syntax change in nginx 1.25.1, hardcoded X-Forwarded-Proto.
  • 🔒 Hardening — security headers done right, rate limiting, real-IP behind a CDN, TLS tuning, OCSP, HTTP/3.

What's inside

nginx/
├── SKILL.md                       # entry point: workflow, decision tree, checklist
├── references/
│   ├── diagnostics.md             # "site won't load" — diagnose from logs first
│   ├── proxy-patterns.md          # reverse proxy, WebSocket, SPA/Next.js, S3/MinIO
│   ├── tls-ssl.md                 # certs, HTTP/2 & HTTP/3, TLS tuning, redirects
│   ├── performance-mobile.md      # caching, gzip/brotli, buffers, MTU, BBR
│   ├── security.md                # headers, rate limiting, real-IP, geo
│   └── anti-patterns.md           # the gotchas that cause most "nginx bugs"
└── scripts/
    ├── nginx-check.sh             # read-only: nginx -t + version + anti-pattern scan
    └── diagnose-ip.sh             # classify a connectivity complaint from the access log

The skill uses progressive disclosure: SKILL.md stays short and routes to the deep reference for the task at hand, so context isn't wasted loading everything at once.

Install

Claude Code (CLI / IDE)

Personal (all your projects):

git clone https://github.com/tensorshift/claude-nginx-skill.git
cp -r claude-nginx-skill/nginx ~/.claude/skills/nginx

Project-scoped (share with your team via the repo):

mkdir -p .claude/skills
cp -r claude-nginx-skill/nginx .claude/skills/nginx
git add .claude/skills/nginx && git commit -m "Add nginx skill"

Then in a session just ask naturally — "review this nginx config", "the site won't load on mobile", "set up a reverse proxy with websockets" — and the skill activates on its own. (Restart Claude Code if it was running during install.)

Claude apps / Agent SDK

Drop the nginx/ folder into your skills directory (or upload as a Skill in the app). The SKILL.md frontmatter (name, description) is what Claude matches against.

Make the scripts executable

chmod +x nginx/scripts/*.sh
nginx/scripts/nginx-check.sh /etc/nginx           # scan your configs (read-only)
nginx/scripts/diagnose-ip.sh 203.0.113.7          # classify a complaint by IP

Both scripts make no changes; they're safe on production.

Design principles

  1. Diagnose, don't guess. The access log keyed by the user's IP tells you whether a request even arrived. "Seems better" is not a fix.
  2. One concern per change, always validated with nginx -t and a reload (not restart).
  3. Version-aware. Several directives changed syntax across releases; the skill picks the form that matches the running nginx.
  4. Never touch certs unasked. # managed by Certbot lines are left alone.

Contributing

Found another real-world gotcha? PRs welcome — add it to the relevant reference and, if detectable, a grep rule to nginx-check.sh.

License

MIT — see LICENSE. Use it, fork it, share it with your team.

Built collaboratively with Claude Code, distilled from real incident debugging. Not affiliated with nginx or F5.

Ver o original no GitHub

Bom para

Relacionados