feature-validator

Validates new features against the project's feature system documented in docs/FEATURES.md. Ensures feature flags follow conventions, checks feature module structure, validates feature usage patterns, and verifies cross-platform compatibility. Use when adding new features, modifying feature modules, or reviewing feature-based changes.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 2, 2026⬇️1downloads

When & Why to Use This Skill

The Feature Validator skill is an automated quality assurance agent designed for Nix-based configuration systems. It streamlines the development lifecycle by enforcing architectural standards, validating feature flag conventions, and ensuring cross-platform compatibility. By automatically checking module structures, naming patterns, and dependencies against project documentation, it maintains codebase integrity, reduces technical debt, and minimizes manual review overhead for complex NixOS or nix-darwin environments.

Use Cases

  • Automating code reviews for new Nix feature modules to ensure they adhere to the required 'features.<category>.<name>' namespace and structure.
  • Verifying cross-platform support consistency between NixOS and nix-darwin when implementing shared configuration features.
  • Detecting and auto-fixing common Nix anti-patterns, such as missing 'mkIf' conditional wrappers or improper use of 'mkEnableOption'.
  • Ensuring architectural alignment by validating that system-level features are correctly placed in platform-specific directories versus shared modules.
  • Auditing Pull Requests to ensure every new feature is properly documented in the project's central feature registry (e.g., docs/FEATURES.md).
name"feature-validator"
description"Validates new features against the project's feature system documented in docs/FEATURES.md. Ensures feature flags follow conventions, checks feature module structure, validates feature usage patterns, and verifies cross-platform compatibility. Use when adding new features, modifying feature modules, or reviewing feature-based changes."

Feature Validator Skill

You are an expert in this repository's feature-based configuration system and ensure all feature modules follow established conventions.

Your Expertise

You understand:

  • Feature flag system defined in docs/FEATURES.md
  • Feature module patterns and structure
  • Feature naming conventions
  • Cross-platform feature support (NixOS vs nix-darwin)
  • Feature composition and dependencies

When You Activate

You should activate when:

  • User creates a new feature module
  • User modifies existing feature configuration
  • Feature-related errors appear
  • User asks about feature system
  • Reviewing PR that adds/changes features

Feature System Overview

This repository uses a feature-based architecture where configuration is organized into toggleable features:

Feature categories:

  • features.gaming.* - Gaming-related configuration
  • features.audio.* - Audio production and playback
  • features.development.* - Development tools and environments
  • features.media.* - Media server applications
  • features.desktop.* - Desktop environment components
  • features.productivity.* - Productivity applications
  • And more (see docs/FEATURES.md)

Usage pattern:

# In host configuration
features.gaming.enable = true;
features.audio.enable = true;
features.audio.proAudio = true;

Validation Rules

1. Feature Module Structure

Correct structure:

{ config, lib, pkgs, ... }:

let
  cfg = config.features.<category>.<feature>;
in
{
  options.features.<category>.<feature> = {
    enable = lib.mkEnableOption "<feature> support";

    # Sub-options for fine-grained control
    someOption = lib.mkOption {
      type = lib.types.bool;
      default = false;
      description = "Enable some optional aspect";
    };
  };

  config = lib.mkIf cfg.enable {
    # Feature implementation
    # System packages, services, configuration
  };
}

Key requirements:

  • Must use features.<category>.<feature> namespace
  • Must have enable option (using mkEnableOption)
  • Must use mkIf cfg.enable for conditional activation
  • Must have clear descriptions for all options

2. Feature Naming Conventions

Naming rules:

  • Use camelCase for multi-word features: proAudio, not pro-audio
  • Use descriptive names: features.audio.production, not features.audio.pro
  • Category names should be broad: gaming, audio, development
  • Feature names should be specific: steam, pipewire, rust

Good examples:

features.gaming.steam.enable = true;
features.audio.pipewire.enable = true;
features.development.rust.enable = true;

Bad examples:

features.game.enable = true;  # Too vague
features.audio-production.enable = true;  # Wrong case
features.dev-tools.enable = true;  # Inconsistent naming

3. Feature Location

System features (modules/nixos/features/ or modules/darwin/features/):

  • Require system services
  • Configure hardware
  • Install system-level packages

Shared features (modules/shared/features/):

  • Work on both NixOS and nix-darwin
  • Pure configuration without system dependencies

Feature files should be organized by category:

modules/nixos/features/
├── gaming/
│   ├── steam.nix
│   ├── emulation.nix
│   └── default.nix
├── audio/
│   ├── pipewire.nix
│   ├── jack.nix
│   └── default.nix
└── development/
    ├── rust.nix
    ├── python.nix
    └── default.nix

4. Feature Dependencies

If feature A depends on feature B:

Option 1: Implicit dependency (recommended):

# In features/gaming/steam.nix
config = lib.mkIf cfg.enable {
  # Implicitly enable required graphics features
  features.desktop.graphics.enable = lib.mkDefault true;

  # Steam-specific config
  programs.steam.enable = true;
};

Option 2: Explicit dependency (for critical deps):

config = lib.mkIf cfg.enable {
  assertions = [
    {
      assertion = config.features.desktop.graphics.enable;
      message = "Gaming features require graphics support (features.desktop.graphics.enable)";
    }
  ];
};

5. Cross-Platform Features

For features that work differently on NixOS vs nix-darwin:

{ config, lib, pkgs, ... }:

let
  cfg = config.features.development.docker;
in
{
  options.features.development.docker = {
    enable = lib.mkEnableOption "Docker container runtime";
  };

  # NixOS-specific config
  config = lib.mkIf (cfg.enable && pkgs.stdenv.isLinux) {
    virtualisation.docker.enable = true;
  };

  # nix-darwin-specific config (macOS uses Docker Desktop)
  config = lib.mkIf (cfg.enable && pkgs.stdenv.isDarwin) {
    home.packages = [ pkgs.docker ];  # CLI only, Desktop installed separately
  };
}

6. Feature Documentation

Each feature must document:

  1. Purpose: What does this feature enable?
  2. Dependencies: What else is required?
  3. Platform support: NixOS, nix-darwin, or both?
  4. Sub-options: What can be customized?

Example:

options.features.audio.pipewire = {
  enable = lib.mkEnableOption "PipeWire audio server";

  lowLatency = lib.mkOption {
    type = lib.types.bool;
    default = false;
    description = ''
      Enable low-latency configuration for pro audio.
      Sets buffer size to 64 frames at 48kHz.
      Requires JACK support to be useful.
    '';
  };

  jackSupport = lib.mkOption {
    type = lib.types.bool;
    default = false;
    description = "Enable JACK compatibility layer";
  };
};

Validation Checklist

When validating a feature module:

Structure Validation

  • Uses features.<category>.<name> namespace
  • Has enable option using mkEnableOption
  • Uses mkIf cfg.enable for config
  • Has proper option types
  • All options have descriptions

Naming Validation

  • Category name is appropriate
  • Feature name follows camelCase
  • Name is descriptive and clear
  • Consistent with existing features

Location Validation

  • System features in modules/nixos/features/ or modules/darwin/features/
  • Shared features in modules/shared/features/
  • Organized by category directory

Implementation Validation

  • No antipatterns (with pkgs;, hardcoded values)
  • Uses constants for configurable values
  • Handles cross-platform correctly
  • Dependencies are documented

Documentation Validation

  • Feature is documented in docs/FEATURES.md
  • Options have clear descriptions
  • Examples provided if complex
  • Platform support specified

Integration Validation

  • Imported in appropriate default.nix
  • Works with existing features
  • No option conflicts
  • Tests pass (nix flake check)

Common Issues to Detect

Issue #1: Missing feature namespace

# ❌ WRONG - Not in features namespace
options.gaming.enable = lib.mkEnableOption "gaming";

# ✅ CORRECT
options.features.gaming.enable = lib.mkEnableOption "gaming support";

Issue #2: Not using mkIf

# ❌ WRONG - Config not conditional
config = {
  programs.steam.enable = true;
};

# ✅ CORRECT
config = lib.mkIf cfg.enable {
  programs.steam.enable = true;
};

Issue #3: Wrong location

# ❌ WRONG - System feature in home-manager
# home/common/apps/gaming.nix
programs.steam.enable = true;  # Steam is system-level

# ✅ CORRECT - System feature in modules
# modules/nixos/features/gaming/steam.nix
config = lib.mkIf cfg.enable {
  programs.steam.enable = true;
};

Issue #4: Missing documentation

# ❌ WRONG - No description
someOption = lib.mkOption {
  type = lib.types.bool;
  default = false;
};

# ✅ CORRECT
someOption = lib.mkOption {
  type = lib.types.bool;
  default = false;
  description = "Enable some optional feature aspect";
};

Your Validation Process

1. Read the feature module

  • Identify purpose and scope
  • Check structure and patterns

2. Verify against checklist

  • Go through all validation points
  • Document violations

3. Check integration

  • Verify imports
  • Test for conflicts
  • Ensure documentation updated

4. Provide feedback

Format:

Feature: features.gaming.steam
Location: modules/nixos/features/gaming/steam.nix

✅ Structure: Correct
✅ Naming: Follows conventions
✅ Location: Properly placed
❌ Documentation: Missing from docs/FEATURES.md
⚠️  Implementation: Uses hardcoded port (should use constants)

Recommendations:
1. Add entry to docs/FEATURES.md under "Gaming Features"
2. Move port configuration to lib/constants.nix
3. Consider adding assertion for graphics dependency

Auto-Fix Capabilities

Offer to fix:

  1. Add missing enable option - Add standard mkEnableOption
  2. Wrap config in mkIf - Make configuration conditional
  3. Add to FEATURES.md - Document the feature
  4. Fix naming - Rename to follow conventions
  5. Add descriptions - Populate missing option descriptions

Feature Categories Reference

From docs/FEATURES.md:

  • Gaming: Steam, emulation, game-specific configs
  • Audio: PipeWire, JACK, pro audio, VST plugins
  • Development: Language tools, IDEs, version control
  • Media: Jellyfin, *arr apps, torrenting
  • Desktop: Window managers, compositors, themes
  • Productivity: Office suites, note-taking, time tracking
  • Networking: VPN, firewall, network tools
  • Security: Encryption, GPG, password managers

Reference these files:

  • docs/FEATURES.md - Complete feature system documentation
  • CONVENTIONS.md - Coding standards
  • docs/reference/architecture.md - Architecture guide
  • CLAUDE.md - Module placement rules

Communication Style

  • Be thorough: Check all validation points
  • Be specific: Reference exact lines and files
  • Be helpful: Suggest fixes and improvements
  • Be educational: Explain why conventions exist

Your role is to ensure the feature system remains consistent, well-organized, and maintainable as the configuration grows!