Skip to main content
affpapa.org
RU EN
skill CX Codex

nginx-c-modules — Claude Code skill: rules for writing nginx C modules

A skill that feeds your agent 49 rules for nginx C module work: pool memory, request lifecycle, config merging. Useful when you write or refactor a handler, filter or upstream.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add pproenca/dot-skills --skill nginx-c-modules -a claude-code
Open on GitHub

What nginx-c-modules does

The skill is derived from the official nginx development guide and split into 8 categories ranked by impact. It holds 49 rules with prefixes mem-, req-, conf-, handler-, filter-, upstream-, event- and ds-, each with its own page under references/. The agent pulls the relevant rule when you start a new module, chase a leak, or touch directive merge logic.

Memory management and request lifecycle carry the CRITICAL mark, and that is where the skill earns its place. Rules push pool allocation over malloc, require a NULL check on every allocation, ask for ngx_pcalloc when initializing structs, and forbid touching a request after finalization. Shared memory zones get the slab allocator. Those are the spots where modules crash or leak.

Config system, handlers, filter chain, upstream and the event loop follow. A few rules stand out: no blocking calls inside event handlers, delete timers before freeing the data they point at, and never assume ngx_str_t is null-terminated. The skill follows the official guide rather than your codebase, so version drift between your nginx and the guide is yours to check.

What it helps with

  • find why a module leaks after switching to malloc
  • write a handler that finalizes the request exactly once
  • merge every config field in merge_loc_conf
  • tell a main request from a subrequest inside a filter
  • move a blocking call out of the event loop into a thread pool

Example prompts for the agent

  • Review my new nginx module against the skill rules — am I allocating outside the pools?
  • Write a content handler that returns JSON and show me where last_buf goes
  • Walk through this upstream module and check my finalize_request cleanup

How to install nginx-c-modules

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill nginx-c-modules -a claude-code

2Manually: put the files in place

~/.claude/skills/nginx-c-modules/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/nginx-c-modules/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about nginx-c-modules

How do I install nginx-c-modules in Claude?

Run npx skills add pproenca/dot-skills --skill nginx-c-modules -a claude-code. The skill lands at ~/.claude/skills/nginx-c-modules/SKILL.md.

What does nginx-c-modules do?

It gives the agent a rule set for nginx C module development: memory management, request lifecycle, configuration, handlers, filters, upstream and the event loop. The agent applies them while you write, review or refactor a module.

Which platforms does the skill support?

Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. Each platform has its own install command and its own path to the skill file.

Source text

SKILL.md · MIT 
---
name: nginx-c-modules
description: nginx C module development guidelines based on the official nginx development guide. This skill should be used when writing, reviewing, or refactoring nginx C modules to ensure correct memory management, request lifecycle handling, and event-driven patterns. Triggers on tasks involving nginx module development, ngx_http_module_t, handler/filter/upstream implementation, pool allocation, or nginx configuration directives.
---

# nginx.org C Module Development Best Practices

Comprehensive development guide for nginx C modules, derived from the official nginx development documentation and community expertise. Contains 49 rules across 8 categories, prioritized by impact to guide correct module implementation and prevent common crashes, memory leaks, and undefined behavior.

## When to Apply

Reference these guidelines when:
- Writing new nginx C modules (handlers, filters, upstream, load-balancers)
- Implementing configuration directives and merge logic
- Managing memory with nginx pools and shared memory zones
- Handling the HTTP request lifecycle (body reading, subrequests, finalization)
- Working with nginx's event loop, timers, and thread pools

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Memory Management | CRITICAL | `mem-` |
| 2 | Request Lifecycle | CRITICAL | `req-` |
| 3 | Configuration System | HIGH | `conf-` |
| 4 | Handler Development | HIGH | `handler-` |
| 5 | Filter Chain | MEDIUM-HIGH | `filter-` |
| 6 | Upstream & Proxy | MEDIUM | `upstream-` |
| 7 | Event Loop & Concurrency | MEDIUM | `event-` |
| 8 | Data Structures & Strings | LOW-MEDIUM | `ds-` |

## Quick Reference

### 1. Memory Management (CRITICAL)

- [`mem-pool-allocation`](references/mem-pool-allocation.md) - Use Pool Allocation Instead of Heap malloc
- [`mem-check-allocation`](references/mem-check-allocation.md) - Check Every Allocation Return for NULL
- [`mem-pcalloc-structs`](references/mem-pcalloc-structs.md) - Use ngx_pcalloc for Struct Initialization
- [`mem-cleanup-handlers`](references/mem-cleanup-handlers.md) - Register Pool Cleanup Handlers for External Resources
- [`mem-pnalloc-strings`](references/mem-pnalloc-strings.md) - Use ngx_pnalloc for String Data Allocation
- [`mem-pfree-limitations`](references/mem-pfree-limitations.md) - Avoid Relying on ngx_pfree for Pool Allocations
- [`mem-shared-slab`](references/mem-shared-slab.md) - Use Slab Allocator for Shared Memory Zones

### 2. Request Lifecycle (CRITICAL)

- [`req-finalize-once`](references/req-finalize-once.md) - Finalize Requests Exactly Once
- [`req-no-access-after-finalize`](references/req-no-access-after-finalize.md) - Never Access Request After Finalization
- [`req-body-async`](references/req-body-async.md) - Handle Request Body Reading Asynchronously
- [`req-discard-body`](references/req-discard-body.md) - Discard Request Body When Not Reading It
- [`req-subrequest-completion`](references/req-subrequest-completion.md) - Use Post-Subrequest Handlers for Completion
- [`req-count-reference`](references/req-count-reference.md) - Increment Request Count Before Async Operations
- [`req-internal-redirect`](references/req-internal-redirect.md) - Return After Internal Redirect

### 3. Configuration System (HIGH)

- [`conf-unset-init`](references/conf-unset-init.md) - Initialize Config Fields with UNSET Constants
- [`conf-merge-all-fields`](references/conf-merge-all-fields.md) - Merge All Config Fields in merge_loc_conf
- [`conf-context-flags`](references/conf-context-flags.md) - Use Correct Context Flags for Directives
- [`conf-null-command`](references/conf-null-command.md) - Terminate Commands Array with ngx_null_command
- [`conf-custom-handler`](references/conf-custom-handler.md) - Use Custom Handlers for Complex Directive Parsing
- [`conf-module-ctx-null`](references/conf-module-ctx-null.md) - Set Unused Module Context Callbacks to NULL
- [`conf-build-config`](references/conf-build-config.md) - Write Correct config Build Script for Module Compilation

### 4. Handler Development (HIGH)

- [`handler-send-header-first`](references/handler-send-header-first.md) - Send Header Before Body Output
- [`handler-last-buf`](references/handler-last-buf.md) - Set last_buf Flag on Final Buffer
- [`handler-phase-registration`](references/handler-phase-registration.md) - Register Phase Handlers in postconfiguration
- [`handler-content-handler`](references/handler-content-handler.md) - Use content_handler for Location-Specific Response Generation
- [`handler-error-page`](references/handler-error-page.md) - Return HTTP Status Codes for Error Responses
- [`handler-empty-response`](references/handler-empty-response.md) - Use header_only for Empty Body Responses
- [`handler-module-ctx`](references/handler-module-ctx.md) - Use Module Context for Per-Request State
- [`handler-add-variable`](references/handler-add-variable.md) - Register Custom Variables in preconfiguration

### 5. Filter Chain (MEDIUM-HIGH)

- [`filter-registration-order`](references/filter-registration-order.md) - Save and Replace Top Filter in postconfiguration
- [`filter-call-next`](references/filter-call-next.md) - Always Call Next Filter in the Chain
- [`filter-check-subrequest`](references/filter-check-subrequest.md) - Distinguish Main Request from Subrequest in Filters
- [`filter-buffer-chain-iteration`](references/filter-buffer-chain-iteration.md) - Iterate Buffer Chains Using cl->next Pattern
- [`filter-buffering-flag`](references/filter-buffering-flag.md) - Set Buffering Flag When Accumulating Response Data

### 6. Upstream & Proxy (MEDIUM)

- [`upstream-create-request`](references/upstream-create-request.md) - Build Complete Request Buffer in create_request
- [`upstream-process-header`](references/upstream-process-header.md) - Parse Upstream Response Incrementally in process_header
- [`upstream-peer-free`](references/upstream-peer-free.md) - Track Failures in Peer free Callback
- [`upstream-finalize`](references/upstream-finalize.md) - Clean Up Resources in finalize_request Callback
- [`upstream-connection-reuse`](references/upstream-connection-reuse.md) - Enable Keepalive for Upstream Connections

### 7. Event Loop & Concurrency (MEDIUM)

- [`event-no-blocking`](references/event-no-blocking.md) - Never Use Blocking Calls in Event Handlers
- [`event-timer-management`](references/event-timer-management.md) - Delete Timers Before Freeing Associated Data
- [`event-handle-read-write`](references/event-handle-read-write.md) - Call ngx_handle_read/write_event After I/O Operations
- [`event-thread-pool`](references/event-thread-pool.md) - Offload Blocking Operations to Thread Pool
- [`event-posted-events`](references/event-posted-events.md) - Use Posted Events for Deferred Processing

### 8. Data Structures & Strings (LOW-MEDIUM)

- [`ds-ngx-str-not-null-terminated`](references/ds-ngx-str-not-null-terminated.md) - Never Assume ngx_str_t Is Null-Terminated
- [`ds-ngx-str-set-literals`](references/ds-ngx-str-set-literals.md) - Use ngx_string Macro Only with String Literals
- [`ds-cpymem-pattern`](references/ds-cpymem-pattern.md) - Use ngx_cpymem for Sequential Buffer Writes
- [`ds-list-iteration`](references/ds-list-iteration.md) - Iterate ngx_list_t Using Part-Based Pattern
- [`ds-hash-readonly`](references/ds-hash-readonly.md) - Build Hash Tables During Configuration Only

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

© pproenca · MIT · pproenca/dot-skills

Similar skills

Everything for Backend and APIs →
nginx-config-optimizer patricio0312rev A skill that writes Nginx configs: reverse proxy, load balancing, caching, SSL and rate limits. Useful when you need to set up or rewrite a server config. CX Codex +1 433installs nginx sanjeed5 A Cursor rule that sets how NGINX configs get written: modular includes, modern TLS, caching and rate limits. Useful when the agent edits your nginx.conf. ★ 3,579repo stars linux-kernel-modules mohitmishra786 Walks your agent through writing and debugging loadable kernel modules: Kbuild, module parameters, /proc, sysfs, character devices, KGDB and ftrace. CX Codex +1 639installs cpp-modules mohitmishra786 A skill that walks your agent through writing, building and debugging C++20 modules: named modules, partitions, header units, CMake and compiler flags. CX Codex +1 555installs m02-resource actionbook Guides AI agents in choosing the right Rust smart pointers and ownership models. Useful when designing data structures or preventing memory leaks. CX Codex +1 3,400installs python-azure-iot-edge-modules official github Guides the design and deployment of Python Azure IoT Edge modules. Useful for edge telemetry pipelines, protocol translation, and offline message queueing. 47installs

From the same set45

react-testing-library A skill with 43 React Testing Library rules. It steers the agent toward tests that check behaviour instead of component internals. CX Codex +1 402installs react-optimise A skill that walks through React app performance: React Compiler, bundle size, rendering, data fetching, Core Web Vitals. Useful when your app feels slow. CX Codex +1 396installs rails-hotwire A skill with Hotwire rules for Rails: Turbo Drive, Frames, Streams, Turbo 8 morphing and Stimulus controllers. Useful when writing or refactoring interactive pages. CX Codex +1 370installs nginx-c-module-design A skill for anyone writing nginx C modules: it helps you decide what to expose as directives, how to name them and where they belong. Most useful while the module's config interface is still being shaped. CX Codex +1 352installs dockerfile-optimise A skill with 48 rules from official Docker docs: layer caching, multi-stage builds, security. Useful when writing or refactoring Dockerfiles. CX Codex +1 344installs uniwind A skill with 45+ rules for Uniwind, the Tailwind bindings for React Native. Useful when setting up a project, building themes or migrating from NativeWind. CX Codex +1 341installs ast-grep A skill with community best practices for writing, reviewing and debugging ast-grep rules for code search, linting and rewriting. CX Codex +1 332installs 37signals-rails A rule set for Ruby on Rails the 37signals way: vanilla Rails, CRUD controllers, rich domain models, Hotwire. Useful when you write or refactor code and want to stay in that school. CX Codex +1 329installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor