[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6FEE5M25MAF4RNEB5QHCY7P":3,"skill-same:01M6FEE5M25MAF4RNEB5QHCY7P":59},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":27,"publishedAt":32,"linkOnly":33,"markdownContent":34,"markdownBody":34,"frontMatter":35,"refName":36,"commitSha":37,"skillDirectory":38,"forksCount":39,"repositoryHtmlUrl":40,"repositoryHomepageUrl":41,"ownerHtmlUrl":42,"ownerBlogUrl":6,"ownerDescription":43,"updatedAt":44,"install":45,"resources":58},"01M6FEE5M25MAF4RNEB5QHCY7P","nginx-c-module-design",null,"ComeOnOliver\u002Fskillshub","ComeOnOliver","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F43215937?v=4","01M6E5JNFECJAAVFE0W7SMWWD2","Haoran Shu","01M6E5JNNDQS7AJZDYFQ8TPZCK",67,"MIT","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fpproenca\u002Fdot-skills\u002Fnginx-c-module-design\u002FSKILL.md",[17,22],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000015","视觉设计","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[28,29,30,31],"design","nginx","module","nginx c module design","2026-11-10 10:12:30",false,"# nginx.org C Module Directive Design Best Practices\n\nComprehensive 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.\n\n## When to Apply\n\nReference these guidelines when:\n- Deciding which values to expose as directives vs hardcode\n- Naming new directives and choosing argument types\n- Selecting scope placement (http, server, location)\n- Setting default values and validation behavior\n- Designing nginx variables for runtime data\n- Deprecating or renaming existing directives\n\n## Companion Skills\n\nThis skill focuses on **design decisions** (the \"what\" and \"why\"). For implementation mechanics, see:\n- **nginx-c-modules** — C implementation: memory pools, request lifecycle, config parsing, handlers, filters\n- **nginx-c-perf** — Performance: buffers, connections, locks, caching, timeouts\n- **nginx-c-debug** — Debugging: crash diagnosis, GDB, tracing, sanitizers\n\n## Rule Categories by Priority\n\n| Priority | Category | Impact | Prefix |\n|----------|----------|--------|--------|\n| 1 | Exposure Decisions | CRITICAL | `expose-` |\n| 2 | Naming Conventions | CRITICAL | `naming-` |\n| 3 | Directive Types | HIGH | `type-` |\n| 4 | Scope Design | HIGH | `scope-` |\n| 5 | Default Values | MEDIUM-HIGH | `default-` |\n| 6 | Validation & Error Messages | MEDIUM | `valid-` |\n| 7 | Variable Design | MEDIUM | `var-` |\n| 8 | Evolution & Compatibility | LOW-MEDIUM | `compat-` |\n\n## Quick Reference\n\n### 1. Exposure Decisions (CRITICAL)\n\n- [`expose-configurable-vs-hardcode`](references\u002Fexpose-configurable-vs-hardcode.md) - Framework for Configurable vs Hardcoded Values\n- [`expose-escape-hatch`](references\u002Fexpose-escape-hatch.md) - Provide Escape Hatches for Hardcoded Defaults\n- [`expose-feature-gate`](references\u002Fexpose-feature-gate.md) - Use Feature Gates for Optional Behavior\n- [`expose-too-many-directives`](references\u002Fexpose-too-many-directives.md) - Avoid Over-Configuration\n- [`expose-path-resource`](references\u002Fexpose-path-resource.md) - Always Expose External Resource Paths\n- [`expose-security-surface`](references\u002Fexpose-security-surface.md) - Audit Security Implications of Every Exposed Directive\n- [`expose-environment-dependent`](references\u002Fexpose-environment-dependent.md) - Expose Values That Vary by Deployment Environment\n\n### 2. Naming Conventions (CRITICAL)\n\n- [`naming-module-prefix`](references\u002Fnaming-module-prefix.md) - Use a Consistent Module Prefix for All Directives\n- [`naming-sub-prefix-groups`](references\u002Fnaming-sub-prefix-groups.md) - Group Related Directives with Sub-Prefixes\n- [`naming-noun-over-verb`](references\u002Fnaming-noun-over-verb.md) - Prefer Noun Phrases for Directive Names\n- [`naming-no-abbreviations`](references\u002Fnaming-no-abbreviations.md) - Avoid Custom Abbreviations in Directive Names\n- [`naming-cross-module-consistency`](references\u002Fnaming-cross-module-consistency.md) - Mirror Nginx Core Suffix Patterns for Analogous Directives\n- [`naming-lowercase-underscore`](references\u002Fnaming-lowercase-underscore.md) - Use Lowercase with Underscores Only\n\n### 3. Directive Types (HIGH)\n\n- [`type-flag-for-toggles`](references\u002Ftype-flag-for-toggles.md) - Use NGX_CONF_FLAG for Binary Toggles\n- [`type-enum-over-string`](references\u002Ftype-enum-over-string.md) - Use Enum Slot for Known Value Sets\n- [`type-time-size-units`](references\u002Ftype-time-size-units.md) - Use Time and Size Slot Functions for Time and Size Values\n- [`type-take-n-fixed-args`](references\u002Ftype-take-n-fixed-args.md) - Use TAKE1\u002FTAKE2\u002FTAKE12 for Fixed Argument Counts\n- [`type-one-more-lists`](references\u002Ftype-one-more-lists.md) - Use 1MORE for Variable-Length Value Lists\n- [`type-avoid-block`](references\u002Ftype-avoid-block.md) - Avoid Block Directives for Features\n- [`type-custom-handler-complex`](references\u002Ftype-custom-handler-complex.md) - Use Custom Handlers for Complex Directive Parsing\n\n### 4. Scope Design (HIGH)\n\n- [`scope-default-three-levels`](references\u002Fscope-default-three-levels.md) - Default to http + server + location Scope\n- [`scope-http-only-shared-resources`](references\u002Fscope-http-only-shared-resources.md) - Restrict Shared Resource Directives to http Level Only\n- [`scope-server-connection-level`](references\u002Fscope-server-connection-level.md) - Use http + server Scope for Connection-Level Settings\n- [`scope-avoid-if-context`](references\u002Fscope-avoid-if-context.md) - Do Not Support the if Context Unless Fully Tested\n- [`scope-location-path-operations`](references\u002Fscope-location-path-operations.md) - Restrict Path-Routing Directives to Location Context\n\n### 5. Default Values (MEDIUM-HIGH)\n\n- [`default-zero-config-safe`](references\u002Fdefault-zero-config-safe.md) - Ensure Zero-Config Produces Safe Behavior\n- [`default-performance-optin`](references\u002Fdefault-performance-optin.md) - Make Performance Features Opt-In\n- [`default-safety-on`](references\u002Fdefault-safety-on.md) - Default Security Settings to Restrictive Values\n- [`default-generous-timeouts`](references\u002Fdefault-generous-timeouts.md) - Default Timeouts to Generous Values\n- [`default-zero-unlimited`](references\u002Fdefault-zero-unlimited.md) - Use Zero to Mean Unlimited or Disabled for Numeric Limits\n- [`default-platform-aware-buffers`](references\u002Fdefault-platform-aware-buffers.md) - Use Platform-Aware Buffer Size Defaults\n\n### 6. Validation & Error Messages (MEDIUM)\n\n- [`valid-parse-time-check`](references\u002Fvalid-parse-time-check.md) - Validate All Directive Values at Config Parse Time\n- [`valid-show-invalid-value`](references\u002Fvalid-show-invalid-value.md) - Include the Invalid Value in Error Messages\n- [`valid-suggest-range`](references\u002Fvalid-suggest-range.md) - Include Valid Range or Format in Error Messages\n- [`valid-conflict-detection`](references\u002Fvalid-conflict-detection.md) - Detect Conflicting Directives at Merge Time\n- [`valid-actionable-guidance`](references\u002Fvalid-actionable-guidance.md) - Provide Actionable Guidance in Error Messages\n\n### 7. Variable Design (MEDIUM)\n\n- [`var-runtime-data-only`](references\u002Fvar-runtime-data-only.md) - Expose Variables for Per-Request Runtime Data Only\n- [`var-naming-convention`](references\u002Fvar-naming-convention.md) - Name Variables with Module Prefix and Descriptive Suffix\n- [`var-dynamic-prefix`](references\u002Fvar-dynamic-prefix.md) - Use Dynamic Prefix Variables for Key-Value Data\n- [`var-lazy-evaluation`](references\u002Fvar-lazy-evaluation.md) - Leverage Lazy Evaluation for Expensive Variables\n- [`var-in-directive-values`](references\u002Fvar-in-directive-values.md) - Support Variables in Directive Values Only When Per-Request Variation Is Needed\n- [`var-read-only-diagnostics`](references\u002Fvar-read-only-diagnostics.md) - Expose Read-Only Diagnostic Variables for Observability\n\n### 8. Evolution & Compatibility (LOW-MEDIUM)\n\n- [`compat-deprecation-warning`](references\u002Fcompat-deprecation-warning.md) - Log Warnings for Deprecated Directives Before Removal\n- [`compat-alias-old-directive`](references\u002Fcompat-alias-old-directive.md) - Keep Old Directive Name as an Alias\n- [`compat-multi-version-window`](references\u002Fcompat-multi-version-window.md) - Maintain a Multi-Version Deprecation Window\n- [`compat-document-migration`](references\u002Fcompat-document-migration.md) - Document Migration Path in Both Old and New Directive Documentation\n\n## How to Use\n\nRead individual reference files for detailed explanations and code examples:\n\n- [Section definitions](references\u002F_sections.md) - Category structure and impact levels\n- [Rule template](assets\u002Ftemplates\u002F_template.md) - Template for adding new rules\n\n## Reference Files\n\n| File | Description |\n|------|-------------|\n| [references\u002F_sections.md](references\u002F_sections.md) | Category definitions and ordering |\n| [assets\u002Ftemplates\u002F_template.md](assets\u002Ftemplates\u002F_template.md) | Template for new rules |\n| [metadata.json](metadata.json) | Version and reference information |\n",{},"main","def8531e65114c0fca8fb8551c1871ee0eed705c","skills\u002Fpproenca\u002Fdot-skills\u002Fnginx-c-module-design",24,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub","https:\u002F\u002Fskillshub.wtf","https:\u002F\u002Fgithub.com\u002FComeOnOliver","AI & Blockchain Engineer\r\n","2026-06-24 22:07:19",{"source":7,"skillName":5,"commands":46,"prompt":56,"zipAvailable":57},[47,50,53],{"tool":48,"command":49},"npx","npx skills add ComeOnOliver\u002Fskillshub --skill nginx-c-module-design",{"tool":51,"command":52},"bunx","bunx skills add ComeOnOliver\u002Fskillshub --skill nginx-c-module-design",{"tool":54,"command":55},"pnpm","pnpm dlx skills add ComeOnOliver\u002Fskillshub --skill nginx-c-module-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fpproenca\u002Fdot-skills\u002Fnginx-c-module-design\u002FSKILL.md",true,[],[60,72,82,91,97,104],{"skillNo":61,"name":62,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":68,"publishedAt":32},"01M6FKJN13GMG4KY57J3QD8GY5","model-hierarchy-skill","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzscole\u002Fmodel-hierarchy-skill\u002Fmodel-hierarchy-skill\u002FSKILL.md",[65],{"categoryNo":66,"categoryName":67,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发",[69,70,71],"model","model hierarchy","model hierarchy skill",{"skillNo":73,"name":74,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":78,"publishedAt":32},"01M6FKJJJ6GCAMR4PPPRD12M5X","zoom-mcp","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-mcp\u002FSKILL.md",[77],{"categoryNo":66,"categoryName":67,"taxonomyType":20,"taxonomyTypeDesc":21},[79,80,81],"MCP","zoom","zoom mcp",{"skillNo":83,"name":84,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":32},"01M6FKJE3KYT3KPEZMEEHYKA6K","zoom-apps-sdk","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-apps-sdk\u002FSKILL.md",[],[88,89,90,80],"sdk","zoom apps sdk","apps",{"skillNo":92,"name":93,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":32},"01M6FKJ9EDH9Q5VWDF8HAJRSP0","windows","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwindows\u002FSKILL.md",[],[93],{"skillNo":98,"name":99,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":103,"publishedAt":32},"01M6FKJ666BEEFC3AE9GJ72Q93","whiteboard","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwhiteboard\u002FSKILL.md",[102],{"categoryNo":66,"categoryName":67,"taxonomyType":20,"taxonomyTypeDesc":21},[99],{"skillNo":105,"name":106,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":32},"01M6FKJ21WFCDGTJQ2Q91T9DVW","websockets","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwebsockets\u002FSKILL.md",[],[106]]