Agent skill

NGINX Ingress Controller Feature Checklists

by nginx in nginx/kubernetes-ingress

Gives step-by-step checklists for adding Ingress annotations, VirtualServer fields and Helm values to the NGINX Kubernetes Ingress Controller, with common gotchas.

Apache-2.0Auto-check passedDevOps & Cloud

Install NGINX Ingress Controller Feature Checklists

skills CLI
$ npx skills add nginx/kubernetes-ingress --skill nic-add-feature -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install nginx/kubernetes-ingress nic-add-feature --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/nginx/kubernetes-ingress.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.github/skills/nic-add-feature .claude/skills/nic-add-feature && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
nic-add-feature
GitHub stars
5.1k
Token cost
~1.4k tokens
SKILL.md length
552 words
Files
1
Skills in repo
9
Repo updated
First seen
Licence
Apache-2.0

At a glance

Gives step-by-step checklists for adding Ingress annotations, VirtualServer fields and Helm values to the NGINX Kubernetes Ingress Controller, with common gotchas.

  • Works in 9 steps: Add constant in… → Add field to ConfigParams in… → Parse it in parseAnnotations() in… → …
  • Adding a new Ingress annotation to the NGINX Ingress Controller
  • SKILL.md covers Adding a New Annotation…, Adding a New VirtualServer/VSR… and Adding a Helm Chart Value
  • Calls make

What it does

For a new annotation, which applies only to Ingress objects, the checklist runs from the constant and a `ConfigParams` field through parsing, the master and minion denylists, config generation, the NGINX directive in both the open source and Plus templates, validation, tests and a snapshot case refreshed with `make test-update-snaps`. Gotchas include remembering both template files unless a directive is Plus-only, using `containsDangerousChars()` for user strings and the fact that unknown annotations are ignored silently.

For a VirtualServer or VirtualServerRoute field, it covers adding the field with kubebuilder markers in the API types, running `make update-codegen` and `make update-crds`, adding validation, extending the version 2 template struct, wiring the config generator and rendering it in the VirtualServer templates. The description also covers new NGINX directives, CRD fields and Helm chart values.

When your agent uses it

  • Adding a new Ingress annotation to the NGINX Ingress Controller
  • Adding a field to the VirtualServer or VirtualServerRoute resources
  • Exposing a new NGINX directive through configuration
  • Adding a Helm chart value for the controller

Example prompts

  • “Add an annotation that sets a proxy buffer size on Ingress resources, with templates and tests.”
  • “Add a new field to VirtualServer routes and regenerate the CRDs.”
  • “My annotation change shows no snapshot diff. What did I miss?”

Requirements

  • A checkout of the nginx/kubernetes-ingress repository
  • `make` for the codegen and snapshot targets

Workflow steps

9 steps, taken from the first numbered list in SKILL.md.

  1. Add constant in internal/configs/annotations.go (e.g., MyAnnotation = "nginx.org/my-annotation")
  2. Add field to ConfigParams in internal/configs/config_params.go
  3. Parse it in parseAnnotations() in internal/configs/annotations.go
  4. Update masterDenylist / minionDenylist if it should not be on master/minion
  5. Apply it in generateNginxCfg() in internal/configs/ingress.go
  6. Add the NGINX directive in internal/configs/version1/nginx.ingress.tmpl and internal/configs/version1/nginx-plus.ingress.tmpl
  7. Add validation in internal/k8s/validation.go annotation validation chains
  8. Add tests in annotations_test.go and ingress_test.go
  9. Add a snapshot case in internal/configs/version1/template_test.go whose fixture sets the new ConfigParams field, then run make…

What it can do on your machine

Read from SKILL.md and the folder at commit 03e1429. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • make

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

NGINX Ingress Controller Feature Checklists loads about 1.4k tokens when it runs. Until then it costs about 58 tokens; SKILL.md has 552 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~58
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from nginx/kubernetes-ingress at commit 03e1429, republished under its Apache-2.0 licence (© nginx). 552 words, ~1,449 tokens.

Download SKILL.mdSave it as .claude/skills/nic-add-feature/SKILL.md (or your agent's skills folder).
name
nic-add-feature
description
Checklists for adding Ingress annotations, VirtualServer/VSR fields, or Helm chart values to NIC. Use when adding new configuration options, new NGINX directives, new annotations, new CRD fields, or new Helm values.

Adding Features to NIC

Adding a New Annotation (Ingress Only)

Annotations apply ONLY to Ingress objects, never to VirtualServer or VirtualServerRoute.

  1. Add constant in internal/configs/annotations.go (e.g., MyAnnotation = "nginx.org/my-annotation")
  2. Add field to ConfigParams in internal/configs/config_params.go
  3. Parse it in parseAnnotations() in internal/configs/annotations.go
  4. Update masterDenylist / minionDenylist if it should not be on master/minion
  5. Apply it in generateNginxCfg() in internal/configs/ingress.go
  6. Add the NGINX directive in internal/configs/version1/nginx.ingress.tmpl and internal/configs/version1/nginx-plus.ingress.tmpl
  7. Add validation in internal/k8s/validation.go annotation validation chains
  8. Add tests in annotations_test.go and ingress_test.go
  9. Add a snapshot case in internal/configs/version1/template_test.go whose fixture sets the new ConfigParams field, then run make test-update-snaps and confirm the directive appears in internal/configs/version1/__snapshots__/ for every edition the annotation supports -- both OSS and Plus for shared directives, Plus golden files only for Plus-only ones
Gotchas
  • Never forget both OSS and Plus templates -- they are separate files. The exception is a Plus-only directive, which belongs in the Plus template only
  • Use containsDangerousChars() for any user-provided string that ends up in NGINX config
  • parseAnnotations() silently ignores unknown annotations -- add the constant first
  • An unchanged __snapshots__ diff after a .tmpl edit means no fixture exercises the new branch -- the annotation is untested

Adding a New VirtualServer/VSR Field

  1. Add field to the appropriate struct in pkg/apis/configuration/v1/types.go with kubebuilder markers
  2. Run make update-codegen and make update-crds
  3. Add validation in pkg/apis/configuration/validation/virtualserver.go
  4. Add to the version2 template struct in internal/configs/version2/http.go
  5. Wire in internal/configs/virtualserver.go (GenerateVirtualServerConfig or helper)
  6. Add template rendering in nginx.virtualserver.tmpl / nginx-plus.virtualserver.tmpl
  7. Add a snapshot case in internal/configs/version2/templates_test.go that populates the new field in the fixture, then run make test-update-snaps and verify the directive appears in internal/configs/version2/__snapshots__/ for every edition the field supports -- both OSS and Plus for shared directives, Plus golden files only for Plus-only ones
  8. Check whether Ingress (v1) needs the same capability as an annotation
JSON Tag Conventions
  • NGINX-proxy-related fields: kebab-case (json:"lb-method", json:"fail-timeout")
  • K8s/application fields: camelCase (json:"ingressClassName", json:"rewritePath")
Pointer vs Value Types
  • *int, *bool, *SomeStruct = optional/nullable
  • Plain int, bool = required or zero-value default
  • Booleans defaulting to false must be non-pointer
Show full SKILL.md (212 more words)Show less
Kubebuilder Markers
MarkerPurpose
+kubebuilder:validation:RequiredField must be present
+kubebuilder:validation:OptionalField is optional
+kubebuilder:validation:Pattern= `regex`Regex validation
+kubebuilder:validation:Minimum=NNumeric minimum
+kubebuilder:validation:MinItems=N / MaxItems=NArray length
+kubebuilder:validation:MaxLength=NMax string length
+kubebuilder:default=valueDefault value
+kubebuilder:validation:XValidation:rule="CEL"Cross-field CEL validation
CEL Validation Examples
go
// Prevent wildcard origin with credentials
// +kubebuilder:validation:XValidation:rule="!(self.allowOrigin.exists(origin, origin == '*') && has(self.allowCredentials) && self.allowCredentials == true)",message="..."

// Require time when allowedCodes is set
// +kubebuilder:validation:XValidation:rule="!has(self.allowedCodes) || (has(self.allowedCodes) && has(self.time))",message="..."
Gotchas
  • Never skip make update-codegen after changing types.go
  • Never edit zz_generated.deepcopy.go manually
  • make update-crds also refreshes deploy/crds*.yaml and docs/crd/ -- commit all of it
  • charts/nginx-ingress/crds is a symlink to config/crd/bases/ -- never edit it directly
  • Version 2 has a single Server block; Version 1 has multiple Server blocks

Adding a Helm Chart Value

  1. Add to charts/nginx-ingress/values.yaml with ## documentation above the field
  2. Add JSON schema in charts/nginx-ingress/values.schema.json
  3. If it maps to a CLI arg: add to nginx-ingress.args in charts/nginx-ingress/templates/_helpers.tpl
  4. If it maps to a ConfigMap key: add to charts/nginx-ingress/templates/controller-configmap.yaml
  5. If it needs volumes/mounts: add to the volume helpers in _helpers.tpl
  6. Create a testdata file in charts/tests/testdata/<feature>.yaml
  7. Add test case in charts/tests/helmunit_test.go
  8. Run make test-update-snaps and confirm charts/tests/__snapshots__/ contains the rendered value
Gotchas
  • Always update all three workload templates (deployment, daemonset, statefulset) when they share logic via helpers
  • Always update values.schema.json alongside values.yaml
  • Helm tests use terratest + go-snaps: charts/tests/helmunit_test.go, gated behind the helmunit build tag
  • A chart change with no charts/tests/__snapshots__ diff means no testdata file renders the new value

© nginx, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .github/skills/nic-add-feature of nginx/kubernetes-ingress.

Open the folder on GitHubat commit 03e1429

Compare with similar skills

NGINX Ingress Controller Feature Checklists next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

NGINX Ingress Controller Feature Checklists compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
NGINX Ingress Controller Feature Checklists this skillnginx/kubernetes-ingress5.1k—~1.4kAutomated safety check: PassApache-2.0
KubeSphere Gateway Managementkubesphere/kubesphere17k—~2.9kAutomated safety check: PassCustom licence
Nginx To Higress Migrationhigress-group/higress9.5k—~3.9kAutomated safety check: PassApache-2.0
Aks Deployment Skilltimothywarner/chatgptclass143—~916Automated safety check: PassCustom licence
Kubelb Dependency Updateskubermatic/kubelb148—~1.3kAutomated safety check: PassApache-2.0
Ama Logs Update Charts Release Notesmicrosoft/Docker-Provider174—~2.6kAutomated safety check: PassCustom licence

Similar skills

  • KubeSphere Gateway Management

    kubesphere/kubesphere

    Installs, uninstalls, checks and troubleshoots the KubeSphere Gateway extension built on ingress-nginx, including gateways stuck in bad states and Helm or pod failures.

    17k GitHub stars~2.9k tokensUpdated 2 mo ago
    DevOps & CloudAuto-check passed
  • Nginx To Higress Migration

    higress-group/higress

    Migrate from ingress-nginx to Higress in Kubernetes environments.

    9.5k GitHub stars~3.9k tokensUpdated today
    DevOps & CloudAuto-check passed
  • Aks Deployment Skill

    timothywarner/chatgptclass

    Deploy and operate workloads on Azure Kubernetes Service (AKS) the safe way.

    143 GitHub stars~916 tokensUpdated 19 days ago
    DevOps & CloudAuto-check passed
  • Kubelb Dependency Updates

    kubermatic/kubelb

    Sweep and update every dependency surface in the kubelb repo (go.mod, Makefile tool versions, prow images, GitHub Actions, hack/ci pins, addon Helm charts, pinned container images) and split the…

    148 GitHub stars~1.3k tokensUpdated 4 days ago
    DevOps & CloudAuto-check passed
  • Ama Logs Update Charts Release Notes

    microsoft/Docker-Provider

    Official

    Prepare an ama-logs release PR: bump the image tag (X.Y.Z) across Helm charts, manifests, and Dockerfiles, and add a formatted ReleaseNotes.md entry.

    174 GitHub stars~2.6k tokensUpdated yesterday
    DevOps & CloudAuto-check passed
  • Sim Helm

    simstudioai/sim

    Install, upgrade, and operate the Sim Helm chart on Kubernetes.

    30k GitHub stars~2.2k tokensUpdated today
    DevOps & CloudAuto-check passed

More from nginx/kubernetes-ingress

All 9 skills in this repo
  • NGINX Ingress Policy CRD Guide

    nginx/kubernetes-ingress

    Step-by-step checklist for adding a new Policy CRD type to the NGINX Ingress Controller, from the Go types and validation to config generation and templates.

    5.1k GitHub stars~2k tokensUpdated today
    Auto-check passed
  • Explains the multi-stage Dockerfile, the 25 image variant combinations, and the Makefile targets for building NGINX Ingress Controller images.

    5.1k GitHub stars~2.9k tokensUpdated today
    Auto-check passed
  • NGINX Ingress Controller Structure

    nginx/kubernetes-ingress

    Maps the NGINX Kubernetes Ingress Controller codebase: repository layout, architectural layers, layer-crossing rules and which files are generated.

    5.1k GitHub stars~3.8k tokensUpdated today
    Auto-check passed
  • NIC Testing Patterns

    nginx/kubernetes-ingress

    Testing conventions for the NGINX Ingress Controller repo: Go table-driven tests, mandatory snapshot regeneration, Helm tests and Python pytest integration tests.

    5.1k GitHub stars~2.8k tokensUpdated today
    Auto-check passed
  • NGINX Ingress CI Pipelines

    nginx/kubernetes-ingress

    Explains how the NGINX Ingress Controller's GitHub Actions workflows, reusable workflows, build matrices and release pipeline fit together across two repositories.

    5.1k GitHub stars~5.1k tokensUpdated today
    Auto-check passed
  • NGINX Ingress Controller Debugging

    nginx/kubernetes-ingress

    Troubleshooting patterns for the NGINX Ingress Controller: reload failures, custom resources that have no effect, controller panics and snapshot test failures.

    5.1k GitHub stars~1.7k tokensUpdated today
    Auto-check passed

Questions about NGINX Ingress Controller Feature Checklists

What does NGINX Ingress Controller Feature Checklists do?

Gives step-by-step checklists for adding Ingress annotations, VirtualServer fields and Helm values to the NGINX Kubernetes Ingress Controller, with common gotchas. For a new annotation, which applies only to Ingress objects, the checklist runs from the constant and a `ConfigParams` field through parsing, the master and minion denylists, config generation, the NGINX directive in both the open source and Plus templates, validation, tests and a snapshot case refreshed with `make test-update-snaps`. Gotchas include remembering both template files unless a directive is Plus-only, using `containsDangerousChars()` for user strings and the fact that unknown annotations are ignored silently.

When should I use NGINX Ingress Controller Feature Checklists?

NGINX Ingress Controller Feature Checklists fits situations like: adding a new Ingress annotation to the NGINX Ingress Controller; adding a field to the VirtualServer or VirtualServerRoute resources; exposing a new NGINX directive through configuration; adding a Helm chart value for the controller.

How do I install NGINX Ingress Controller Feature Checklists in Claude Code?

Run `npx skills add nginx/kubernetes-ingress --skill nic-add-feature -a claude-code`. Or copy the skill folder (.github/skills/nic-add-feature in nginx/kubernetes-ingress) into .claude/skills/nic-add-feature in your project. Claude Code loads it when a task matches its description.

How do I install NGINX Ingress Controller Feature Checklists in Codex?

Run `npx skills add nginx/kubernetes-ingress --skill nic-add-feature -a codex`. Or copy the skill folder (.github/skills/nic-add-feature in nginx/kubernetes-ingress) into .agents/skills/nic-add-feature in your project. Codex loads it when a task matches its description.

Can I use NGINX Ingress Controller Feature Checklists in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add nginx/kubernetes-ingress --skill nic-add-feature -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/nic-add-feature, .gemini/skills/nic-add-feature, .github/skills/nic-add-feature and .opencode/skills/nic-add-feature in your project.

What does NGINX Ingress Controller Feature Checklists need to run?

Going by SKILL.md and its folder, NGINX Ingress Controller Feature Checklists needs the command-line tools its instructions call (make). Our summary lists: A checkout of the nginx/kubernetes-ingress repository; `make` for the codegen and snapshot targets.

Does NGINX Ingress Controller Feature Checklists access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is NGINX Ingress Controller Feature Checklists safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does NGINX Ingress Controller Feature Checklists use?

NGINX Ingress Controller Feature Checklists is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does NGINX Ingress Controller Feature Checklists use?

About 1.4k tokens (SKILL.md is roughly 5.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to NGINX Ingress Controller Feature Checklists?

Skills that share tags, products or a category with NGINX Ingress Controller Feature Checklists: KubeSphere Gateway Management (kubesphere/kubesphere, 17k stars), Nginx To Higress Migration (higress-group/higress, 9.5k stars), Aks Deployment Skill (timothywarner/chatgptclass, 143 stars) and Kubelb Dependency Updates (kubermatic/kubelb, 148 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains NGINX Ingress Controller Feature Checklists?

nginx (a GitHub organization) maintains it in nginx/kubernetes-ingress, which has 5,081 GitHub stars. The repository holds 9 skills in this directory. The repository was last updated on October 9, 2026.

Source: nginx/kubernetes-ingress on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.