The majority of my day-to-day engineering work is working with Nginx in one way or another. While AI models have come a long way, I’ve noticed they often make very basic mistakes in Nginx configurations.
While you could start every AI task by explaining the tool you’re using to avoid common mistakes, it would be easier if you could just teach the AI to avoid them instead. I recently stumbled upon Agent Skills, which seems to do exactly that. For this reason, I built an Nginx agent skill, which you can find on the nginx-agent-skills GitHub repo.
Agent skills
Agent Skills is an open standard, originally developed by Anthropic, for packaging domain expertise into folders of instructions and resources that AI agents can discover and load on demand. The format is supported by tools like Claude, GitHub Copilot, Cursor, Codex, and others. This means you write the skill once, and it works across platforms.
Nginx agent skill
At the time of writing this post, the skill covers two main areas. The first part is “Nginx gotchas”. I found various AI tools making incorrect assumptions about how Nginx works. For example, it will confidently suggest using if blocks within location contexts, and it will forget the Nginx inheritance model for some directives, such as add_header. It often even hallucinates Nginx directives that don’t exist, or says a directive accepts a variable as a value when it only accepts a fixed string, such as an on/off value. In addition to those common mistakes, the first part also explains how Nginx processes a request and the order in which it matches the locations. Beyond configuration mistakes, there are also undocumented Nginx behaviors that even experienced engineers find surprising. I’ve written about how proxy_cache_lock adds up to 500ms to response times due to its polling mechanism, and how proxy_cache_background_update can block keepalive connections, effectively negating its performance benefits under load.
The second part contains an OpenResty API reference and explains common issues with using OpenResty Lua modules, such as using the cosocket API in a phase where it is not allowed.
How to use
If you’re using Claude.ai, you can install it under Settings → Profile & Skills. For Claude Code, drop the skill folder into your project’s .claude/skills/ or .codex/skills/ directory if you’re using Codex.
Work in progress
This is very much a living project. The initial version covers the basic mistakes I noticed different AI tools make, but there’s more ground to cover, especially security patterns, advanced caching strategies, and testing Nginx configurations.
If you work with Nginx or OpenResty and have opinions about what AI assistants get wrong, contributions and feedback are welcome. Open an issue or submit a PR on GitHub.
If you find it useful, a ⭐ on the repo helps others discover it.