# Nginx Agent Skills

> Nginx & OpenResty Development

- Skill: `comeonoliver/nginx-agent-skills` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comeonoliver/nginx-agent-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comeonoliver/nginx-agent-skills/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ComeOnOliver (https://skillmd.com/u/comeonoliver)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/comeonoliver/nginx-agent-skills

---

# Nginx & OpenResty Development

## Core Guidance

When writing or reviewing Nginx configuration:

1. Always consider the **directive inheritance model**. Child blocks inherit from parent unless they redefine the directive. For example, adding one `proxy_set_header` in a location block wipes all inherited `proxy_set_header` directives from the server block.
2. Prefer `map` over `if` for conditional logic. `if` in location context is dangerous and only reliably supports `return` and `rewrite`. See references/nginx-gotchas.md for the full list.
3. Always clarify `proxy_pass` trailing-slash behavior — it is the single most common source of subtle bugs.
4. When writing `upstream` blocks, always include keepalive configuration and explain connection pooling implications.
5. When writing Nginx directives, always check [docs](https://nginx.org/en/docs/), specifically module references, to verify that a directive actually exists, and what values it accepts (on/off, variable, fixed values, etc).

When writing OpenResty/Lua code:

1. Always check **phase restrictions** before using cosocket or subrequest APIs. See references/openresty-api.md.
2. Prefer `ngx.ctx` over `ngx.var` for passing data between phases because it's more performant.
3. Avoid using ngx.var multiple times for the same variable, as it's less performant than accessing Lua variable.
4. Use `ngx.timer.at` for background/async work, never block the event loop.

When advising on performance:

1. Consult references/testing-patterns.md for benchmarking methodology.
2. Always consider the full request path: client → Nginx → upstream, and tune each segment.
3. Buffer sizing has cascading effects — refer to the buffer tuning section in references/nginx-gotchas.md.

## Reference Files

Load these as needed based on the task:

- **[references/nginx-gotchas.md](references/nginx-gotchas.md)** — Directive behavior gotchas, inheritance rules, location matching, common misconfigurations. Read when writing or debugging any Nginx config.
- **[references/openresty-api.md](references/openresty-api.md)** — Phase handler reference, shared dict operations. Read when writing Lua/OpenResty code.
- **[references/testing-patterns.md](references/testing-patterns.md)** — Config validation. Read when testing or benchmarking.