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

nginx-c-module-design — Claude Code skill: nginx directive 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.

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

What nginx-c-module-design 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.

What it helps with

  • 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 for the agent

  • 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?

How to install nginx-c-module-design

1Skills CLI (Vercel)

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

2Manually: put the files in place

~/.claude/skills/nginx-c-module-design/SKILL.md

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

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

Questions about nginx-c-module-design

How do I install nginx-c-module-design in Claude?

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

What does nginx-c-module-design do?

It gives the agent a rule set for designing nginx C module directives: what to expose in configuration, how to name directives, which scope to pick, what defaults to set and how to validate input.

How is it different from nginx-c-modules?

This one is only about config interface decisions — the what and why. C implementation, memory pools, config parsing and handlers live in the nginx-c-modules skill.

Source text

SKILL.md · MIT 
---
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
- [`expose-feature-gate`](references/expose-feature-gate.md) - Use Feature Gates for Optional Behavior
- [`expose-too-many-directives`](references/expose-too-many-directives.md) - Avoid Over-Configuration
- [`expose-path-resource`](references/expose-path-resource.md) - Always Expose External Resource Paths
- [`expose-security-surface`](references/expose-security-surface.md) - Audit Security Implications of Every Exposed Directive
- [`expose-environment-dependent`](references/expose-environment-dependent.md) - Expose Values That Vary by Deployment Environment

### 2. Naming Conventions (CRITICAL)

- [`naming-module-prefix`](references/naming-module-prefix.md) - Use a Consistent Module Prefix for All Directives
- [`naming-sub-prefix-groups`](references/naming-sub-prefix-groups.md) - Group Related Directives with Sub-Prefixes
- [`naming-noun-over-verb`](references/naming-noun-over-verb.md) - Prefer Noun Phrases for Directive Names
- [`naming-no-abbreviations`](references/naming-no-abbreviations.md) - Avoid Custom Abbreviations in Directive Names
- [`naming-cross-module-consistency`](references/naming-cross-module-consistency.md) - Mirror Nginx Core Suffix Patterns for Analogous Directives
- [`naming-lowercase-underscore`](references/naming-lowercase-underscore.md) - Use Lowercase with Underscores Only

### 3. Directive Types (HIGH)

- [`type-flag-for-toggles`](references/type-flag-for-toggles.md) - Use NGX_CONF_FLAG for Binary Toggles
- [`type-enum-over-string`](references/type-enum-over-string.md) - Use Enum Slot for Known Value Sets
- [`type-time-size-units`](references/type-time-size-units.md) - Use Time and Size Slot Functions for Time and Size Values
- [`type-take-n-fixed-args`](references/type-take-n-fixed-args.md) - Use TAKE1/TAKE2/TAKE12 for Fixed Argument Counts
- [`type-one-more-lists`](references/type-one-more-lists.md) - Use 1MORE for Variable-Length Value Lists
- [`type-avoid-block`](references/type-avoid-block.md) - Avoid Block Directives for Features
- [`type-custom-handler-complex`](references/type-custom-handler-complex.md) - Use Custom Handlers for Complex Directive Parsing

### 4. Scope Design (HIGH)

- [`scope-default-three-levels`](references/scope-default-three-levels.md) - Default to http + server + location Scope
- [`scope-http-only-shared-resources`](references/scope-http-only-shared-resources.md) - Restrict Shared Resource Directives to http Level Only
- [`scope-server-connection-level`](references/scope-server-connection-level.md) - Use http + server Scope for Connection-Level Settings
- [`scope-avoid-if-context`](references/scope-avoid-if-context.md) - Do Not Support the if Context Unless Fully Tested
- [`scope-location-path-operations`](references/scope-location-path-operations.md) - Restrict Path-Routing Directives to Location Context

### 5. Default Values (MEDIUM-HIGH)

- [`default-zero-config-safe`](references/default-zero-config-safe.md) - Ensure Zero-Config Produces Safe Behavior
- [`default-performance-optin`](references/default-performance-optin.md) - Make Performance Features Opt-In
- [`default-safety-on`](references/default-safety-on.md) - Default Security Settings to Restrictive Values
- [`default-generous-timeouts`](references/default-generous-timeouts.md) - Default Timeouts to Generous Values
- [`default-zero-unlimited`](references/default-zero-unlimited.md) - Use Zero to Mean Unlimited or Disabled for Numeric Limits
- [`default-platform-aware-buffers`](references/default-platform-aware-buffers.md) - Use Platform-Aware Buffer Size Defaults

### 6. Validation & Error Messages (MEDIUM)

- [`valid-parse-time-check`](references/valid-parse-time-check.md) - Validate All Directive Values at Config Parse Time
- [`valid-show-invalid-value`](references/valid-show-invalid-value.md) - Include the Invalid Value in Error Messages
- [`valid-suggest-range`](references/valid-suggest-range.md) - Include Valid Range or Format in Error Messages
- [`valid-conflict-detection`](references/valid-conflict-detection.md) - Detect Conflicting Directives at Merge Time
- [`valid-actionable-guidance`](references/valid-actionable-guidance.md) - Provide Actionable Guidance in Error Messages

### 7. Variable Design (MEDIUM)

- [`var-runtime-data-only`](references/var-runtime-data-only.md) - Expose Variables for Per-Request Runtime Data Only
- [`var-naming-convention`](references/var-naming-convention.md) - Name Variables with Module Prefix and Descriptive Suffix
- [`var-dynamic-prefix`](references/var-dynamic-prefix.md) - Use Dynamic Prefix Variables for Key-Value Data
- [`var-lazy-evaluation`](references/var-lazy-evaluation.md) - Leverage Lazy Evaluation for Expensive Variables
- [`var-in-directive-values`](references/var-in-directive-values.md) - Support Variables in Directive Values Only When Per-Request Variation Is Needed
- [`var-read-only-diagnostics`](references/var-read-only-diagnostics.md) - Expose Read-Only Diagnostic Variables for Observability

### 8. Evolution & Compatibility (LOW-MEDIUM)

- [`compat-deprecation-warning`](references/compat-deprecation-warning.md) - Log Warnings for Deprecated Directives Before Removal
- [`compat-alias-old-directive`](references/compat-alias-old-directive.md) - Keep Old Directive Name as an Alias
- [`compat-multi-version-window`](references/compat-multi-version-window.md) - Maintain a Multi-Version Deprecation Window
- [`compat-document-migration`](references/compat-document-migration.md) - Document Migration Path in Both Old and New Directive Documentation

## 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 DevOps and infrastructure →
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 powershell-module-architect VoltAgent Community A subagent for designing and refactoring PowerShell modules, profiles, and automation libraries. Use it when code must work across PowerShell 5.1 and 7+. 183installs golang-cli-cobra-viper Claude MPM Team A skill for building Go command-line tools: command structure with Cobra and configuration from flags, environment variables and files with Viper. CX Codex +1 425installs microsoft-extensions-configuration Aaronontheweb A skill for Claude and other AI editors that guides binding appsettings.json to strongly-typed classes and validating configuration at startup. CX Codex +1 577installs rag-blueprint NVIDIA RAG This skill deploys, configures, troubleshoots, and manages NVIDIA RAG Blueprint. Use it when RAG services run through Docker, Kubernetes, or library workflows. CX Codex +1 3,300installs

From the same set45

expo-react-native-coder A skill with 50 rules and code templates for building Expo and React Native apps. Useful for screens, navigation and auth flows. CX Codex +1 409installs 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-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. CX Codex +1 349installs 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

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