# Nginx

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-tensorshift-claude-nginx-skill-nginx`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tensorshift](https://agentstack.voostack.com/s/tensorshift)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tensorshift](https://github.com/tensorshift)
- **Source:** https://github.com/tensorshift/claude-nginx-skill/tree/main/nginx

## Install

```sh
agentstack add skill-tensorshift-claude-nginx-skill-nginx
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# nginx

Deep, practical guidance for **writing, configuring, reviewing, and debugging**
nginx — a full-spectrum nginx assistant, not just an incident-response tool. Use
it for routine setup (new vhost, reverse proxy, TLS, caching, security) just as
much as for hard problems. On top of standard best practices it encodes
hard-won operational lessons (mobile/MTU black holes, DPI filtering, `add_header`
inheritance traps, HTTP/2 syntax drift across versions) so answers are correct
and version-aware instead of generic snippets.

## What this skill helps with

**Authoring & setup (the everyday case):**

- Stand up a new site / virtual host from scratch (HTTP→HTTPS, certs, HTTP/2).
- Reverse proxy to an app: correct headers, WebSockets, timeouts, keep-alive.
- Frontends (SPA / Next.js / React), object storage (S3/MinIO), APIs.
- Load balancing and `upstream` pools.
- Caching (static + proxy cache), gzip/brotli compression.
- TLS/SSL setup and tuning, HTTP/3, OCSP stapling, redirects.
- Security hardening: headers, rate limiting, real-IP behind a CDN, allow/deny.

**Review & refactor:**

- Audit an existing `.conf` against the checklist below; clean up cruft.

**Debug (when something's wrong):**

- "Won't load", slow on mobile, VPN asymmetry, 502/504/413, redirect loops,
  cert/SNI errors — diagnosed from logs, not guesswork.

## How to use this skill

1. **Identify the task type** and jump to the matching reference. For **setup/
   authoring**, produce a complete, correct config from the patterns in the
   references (adapted to the user's stack), then validate it. For **debugging**,
   diagnose from logs first, then make the minimal correct change — don't paste a
   generic config at a problem you haven't localized.
2. **Always preserve a path to rollback.** Before editing a production `.conf`,
   note the original. Never touch `ssl_certificate*` lines unless explicitly
   asked.
3. **Validate before declaring done.** Every change must pass `nginx -t`. Tell
   the user to run `nginx -t && systemctl reload nginx` (reload, not restart —
   reload is zero-downtime).
4. **Be version-aware.** Several directives changed syntax across nginx
   releases (see Anti-patterns → "HTTP/2 syntax"). When unsure, ask for
   `nginx -v` or use the backward-compatible form.

## Decision tree — pick the right reference

| The user is… | Go to |
|---|---|
| Reporting a site that won't load / loads partially / slow on mobile / works only via VPN | `references/diagnostics.md` (start here — **diagnose, don't guess**) |
| Setting up or fixing a reverse proxy, WebSocket, SPA/Next.js, or S3/MinIO | `references/proxy-patterns.md` |
| Working on certificates, TLS tuning, HTTP/2, HTTP/3, SNI, redirects | `references/tls-ssl.md` |
| Chasing performance: caching, gzip/brotli, buffers, keepalive, MTU | `references/performance-mobile.md` |
| Hardening: security headers, rate limiting, IP allow/deny, real IP behind CDN | `references/security.md` |
| Getting a weird result (headers vanish, redirect loop, 1 server wins) | `references/anti-patterns.md` (read this before blaming nginx) |

## Core review checklist (apply to any `.conf` you touch)

Run through this whenever you review or write a config:

- **`nginx -t` clean?** Syntax + duplicate `server_name` + missing files.
- **HTTP/2 enabled** on `listen 443`? Use the version-correct syntax.
- **Reverse proxy headers** present: `Host`, `X-Real-IP`, `X-Forwarded-For`,
  `X-Forwarded-Proto`? Is `X-Forwarded-Proto` the *real* scheme (`https`, not a
  hardcoded `http`)?
- **WebSocket** endpoints have `proxy_http_version 1.1` + `Upgrade` +
  `Connection` upgrade map?
- **`add_header` inheritance**: does any `location` re-declare `add_header` and
  thereby silently drop security/CORS headers from the parent? (See
  anti-patterns — this is the #1 silent bug.)
- **No `add_header Last-Modified $date_gmt`** or similar cache-busting hacks
  that force clients to re-download everything (kills mobile).
- **No duplicate `server` blocks** / conflicting `server_name`.
- **`if` used only for safe things** (`return`/`rewrite ... last`), never to
  wrap `proxy_pass` or `add_header` (see "if is evil").
- **`client_max_body_size`** set appropriately for upload endpoints (default
  1m causes 413 on file uploads).
- **TLS session reuse** configured (directly or via certbot's
  `options-ssl-nginx.conf`) so mobile clients don't renegotiate per request.
- **Redirects**: single clean `return 301 https://$host$request_uri;` — not a
  pile of certbot `if` blocks.

## Golden rules

- **Diagnose from logs, not vibes.** "Seems better" is not a fix. For
  connectivity/loading complaints, the access log keyed by the user's IP tells
  you whether the request even arrived. See `references/diagnostics.md`.
- **Reload, don't restart.** `systemctl reload nginx` re-reads config with no
  dropped connections. Restart only when changing `worker_*` or modules.
- **One concern per change.** When debugging, change one thing, re-test, keep
  or revert. Don't stack five "fixes" — that's how the bad configs in the wild
  got their cargo-cult cruft.
- **Reproduce the cert layout, never invent it.** If certs are `# managed by
  Certbot`, leave those lines alone; certbot rewrites them on renewal.
- **Prefer `map` over `if`.** Most `if` use cases are better as `map` at
  `http` level.

## Provided scripts

- `scripts/nginx-check.sh` — runs `nginx -t`, prints version, lists every
  `server_name`/`listen` pair to spot duplicates and conflicts, and flags
  common anti-patterns (literal `X-Forwarded-Proto http`, `Last-Modified
  $date_gmt`, missing `http2`, `if` wrapping risky directives). Read-only.
- `scripts/diagnose-ip.sh  [access_log]` — classifies a connectivity
  complaint by grepping the access log for one client IP: requests arriving but
  large responses truncating → server/MTU layer; total silence → path/DPI
  problem upstream of nginx. Implements the workflow in `diagnostics.md`.

Run scripts with the config or log path as argument; they make no changes.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tensorshift](https://github.com/tensorshift)
- **Source:** [tensorshift/claude-nginx-skill](https://github.com/tensorshift/claude-nginx-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tensorshift-claude-nginx-skill-nginx
- Seller: https://agentstack.voostack.com/s/tensorshift
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.