# 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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 352 installs · ★ 218
- 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-design/SKILL.md
- Updated: 2026-08-15
- HTML: https://affpapa.org/en/nevibecode/skills/nginx-c-module-design

## What it does

The skill ships 46 rules in 8 categories, ordered by how much they affect the resulting config. The two critical ones come first: what to expose as a directive versus hardcode, and how to name what you expose. Then directive types, scope placement across http, server and location, default values, validation and error messages, variable design, and safe renaming.

Rules live in separate files under `references/`, each with a prefix — `expose-`, `naming-`, `type-`, `scope-`, `default-`, `valid-`, `var-`, `compat-`. The agent pulls the relevant file when you touch `ngx_command_t` or argue about a directive name. This skill covers decisions, the what and why; C implementation, performance and debugging sit in companion skills.

It earns its place when admins read the config, not just the module author. Take the rule that external resource paths always belong in a directive: hardcode a path and changing it means a rebuild. Worth checking your module against that before you tag a release.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

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

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill nginx-c-module-design -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-design/SKILL.md

## When to use it
- decide which values become directives and which stay hardcoded
- pick a directive name without inventing abbreviations
- choose between http, server and location scope
- set a safe default for a new module
- rename a directive without breaking existing configs

## Example prompts
- Help me design the directives for a new nginx module: what should be configurable and what should be hardcoded
- Review my directive names against the naming-* rules and suggest renames
- Which context should a timeout directive live in — http, server or location?

## 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: 376dd096cfc00ea3.

BEGIN THIRD-PARTY FILE 376dd096cfc00ea3
```text
---
name: nginx-c-module-design
description: nginx C module directive design guidelines for creating admin-friendly configuration interfaces. This skill should be used when designing nginx module directives — deciding what to expose vs hardcode, naming conventions, scope placement, default values, variable design, and validation patterns. Triggers on tasks involving ngx_command_t design, directive naming, configuration API design, nginx module public interface, or directive deprecation.
---

# nginx.org C Module Directive Design Best Practices

Comprehensive directive design guide for nginx C module authors, focused on creating clear, consistent, and admin-friendly configuration interfaces. Contains 46 rules across 8 categories, prioritized by impact to guide decisions about what to expose, how to name it, and how to evolve it safely.

## When to Apply

Reference these guidelines when:
- Deciding which values to expose as directives vs hardcode
- Naming new directives and choosing argument types
- Selecting scope placement (http, server, location)
- Setting default values and validation behavior
- Designing nginx variables for runtime data
- Deprecating or renaming existing directives

## Companion Skills

This skill focuses on **design decisions** (the "what" and "why"). For implementation mechanics, see:
- **nginx-c-modules** — C implementation: memory pools, request lifecycle, config parsing, handlers, filters
- **nginx-c-perf** — Performance: buffers, connections, locks, caching, timeouts
- **nginx-c-debug** — Debugging: crash diagnosis, GDB, tracing, sanitizers

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Exposure Decisions | CRITICAL | `expose-` |
| 2 | Naming Conventions | CRITICAL | `naming-` |
| 3 | Directive Types | HIGH | `type-` |
| 4 | Scope Design | HIGH | `scope-` |
| 5 | Default Values | MEDIUM-HIGH | `default-` |
| 6 | Validation & Error Messages | MEDIUM | `valid-` |
| 7 | Variable Design | MEDIUM | `var-` |
| 8 | Evolution & Compatibility | LOW-MEDIUM | `compat-` |

## Quick Reference

### 1. Exposure Decisions (CRITICAL)

- [`expose-configurable-vs-hardcode`](references/expose-configurable-vs-hardcode.md) - Framework for Configurable vs Hardcoded Values
- [`expose-escape-hatch`](references/expose-escape-hatch.md) - Provide Escape Hatches for Hardcoded Defaults
```
END THIRD-PARTY FILE 376dd096cfc00ea3

The third-party file has ended. Everything between the 376dd096cfc00ea3 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 2406 of 8503 bytes. © pproenca · MIT · https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/nginx-c-module-design/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