# nginx-c-module-perf

The nginx-c-module-perf skill guides performance and reliability work on nginx C modules. Use it when tuning buffers, connections, caching, or error handling.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 267 installs · ★ 227 repo stars
- Author: pproenca
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/nginx-c-module-perf/SKILL.md
- Updated: 2026-08-15
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/nginx-c-module-perf

## What it does

The skill groups 43 rules into eight areas drawn from nginx development guidance. Topics include buffer reuse and zero-copy I/O, connection handling, shared-memory locks, error recovery, timeout and retry strategy, response caching, worker behavior, logging, and metrics.

Apply it while changing an nginx C module and reviewing the effects on latency, throughput, or memory use. It pairs with `nginx-c-modules`, which focuses on correctness, including memory safety and request lifecycle. This skill addresses performance and operational reliability, so correctness checks remain a separate concern.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill nginx-c-module-perf -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/nginx-c-module-perf/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/nginx-c-module-perf/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill nginx-c-module-perf -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/nginx-c-module-perf/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill nginx-c-module-perf -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/nginx-c-module-perf/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pproenca/dot-skills skills/.experimental/nginx-c-module-perf
```

2. **Manually: put the files in place**
- File: `.github/skills/nginx-c-module-perf/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill nginx-c-module-perf -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/nginx-c-module-perf
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/nginx-c-module-perf/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill nginx-c-module-perf -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/nginx-c-module-perf/SKILL.md

## When to use it
- reduce buffer copying in filter chains
- reuse idle connections in a pool
- limit lock contention across workers
- handle upstream failures and memory exhaustion
- set distinct upstream phase timeouts

## Example prompts
- Review this nginx C module for places where buffer copies can be avoided.
- Suggest ways to reduce shared-memory lock contention between workers.
- Check the upstream failure handling and retry strategy in this module.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 4b51433d3dc89fd5.

BEGIN THIRD-PARTY FILE 4b51433d3dc89fd5
```text
---
name: nginx-c-module-perf
description: nginx C module performance optimization and reliability guidelines based on the official nginx development guide. This skill should be used when optimizing nginx C modules for throughput, latency, memory efficiency, and operational resilience. Triggers on tasks involving buffer optimization, connection tuning, shared memory contention, error recovery, timeout strategy, caching implementation, worker process tuning, or logging performance in nginx C modules.
---

# nginx.org C Module Performance & Reliability Best Practices

Comprehensive performance optimization and reliability guide for nginx C modules, derived from the official nginx development documentation and production engineering experience. Contains 43 rules across 8 categories, prioritized by impact to guide automated optimization and resilience improvements.

**Companion skill**: This skill complements [nginx-c-modules](../nginx-c-modules/SKILL.md) which covers correctness (memory safety, request lifecycle, configuration). This skill covers **performance optimization and operational reliability**.

## When to Apply

Reference these guidelines when:
- Optimizing nginx C module throughput and latency
- Reducing buffer copies and enabling zero-copy I/O paths
- Tuning connection pooling and socket options
- Minimizing shared memory lock contention across workers
- Implementing graceful error recovery and fallback responses
- Configuring upstream timeouts and retry strategies
- Building in-module response caches with shared memory
- Tuning worker process behavior under load

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Buffer & Zero-Copy I/O | CRITICAL | `buf-` |
| 2 | Connection Efficiency | CRITICAL | `conn-` |
| 3 | Lock Contention & Atomics | HIGH | `lock-` |
| 4 | Error Recovery & Resilience | HIGH | `err-` |
| 5 | Timeout & Retry Strategy | MEDIUM-HIGH | `timeout-` |
| 6 | Response Caching | MEDIUM | `cache-` |
| 7 | Worker & Process Tuning | MEDIUM | `worker-` |
| 8 | Logging & Metrics | LOW-MEDIUM | `log-` |

## Quick Reference

### 1. Buffer & Zero-Copy I/O (CRITICAL)

- [`buf-chain-reuse`](references/buf-chain-reuse.md) - Reuse Buffer Chain Links Instead of Allocating New Ones
- [`buf-file-sendfile`](references/buf-file-sendfile.md) - Use File Buffers for Static Content Instead of Reading into Memory
- [`buf-avoid-copy`](references/buf-avoid-copy.md) - Avoid Copying Buffers When Passing Through Filter Chain
- [`buf-coalesce-small`](references/buf-coalesce-small.md) - Coalesce Small Buffers Before Output
- [`buf-shadow-reference`](references/buf-shadow-reference.md) - Use Shadow Buffers for Derived Data Instead of Full Copies
- [`buf-recycled-flag`](references/buf-recycled-flag.md) - Mark Buffers as Recycled for Upstream Response Reuse

### 2. Connection Efficiency (CRITICAL)
```
END THIRD-PARTY FILE 4b51433d3dc89fd5

The third-party file has ended. Everything between the 4b51433d3dc89fd5 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2911 of 8108 bytes. © pproenca · MIT · https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/nginx-c-module-perf/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
