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.
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 configurationfeatures.audio.*- Audio production and playbackfeatures.development.*- Development tools and environmentsfeatures.media.*- Media server applicationsfeatures.desktop.*- Desktop environment componentsfeatures.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
enableoption (usingmkEnableOption) - Must use
mkIf cfg.enablefor conditional activation - Must have clear descriptions for all options
2. Feature Naming Conventions
Naming rules:
- Use camelCase for multi-word features:
proAudio, notpro-audio - Use descriptive names:
features.audio.production, notfeatures.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:
- Purpose: What does this feature enable?
- Dependencies: What else is required?
- Platform support: NixOS, nix-darwin, or both?
- 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
enableoption usingmkEnableOption - Uses
mkIf cfg.enablefor 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/ormodules/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:
- Add missing enable option - Add standard
mkEnableOption - Wrap config in mkIf - Make configuration conditional
- Add to FEATURES.md - Document the feature
- Fix naming - Rename to follow conventions
- 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
Related Documentation
Reference these files:
docs/FEATURES.md- Complete feature system documentationCONVENTIONS.md- Coding standardsdocs/reference/architecture.md- Architecture guideCLAUDE.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!