nix-flake-organization

Name: nix-flake-organization
Availability: InStock
Author: darkmatter

Reorganize Nix flake layouts into thin public APIs and feature-oriented src paths.

1|Updated Apr 27, 2026

Search Tags:#refactoring #nix #modules #flakes #flake-parts #home-manager

Ready to run

npx skills add https://github.com/darkmatter/skills --skill nix-flake-organization

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: nix-flake-organization
Source: https://github.com/darkmatter/skills/tree/main/skills/nix-flake-organization
Command: npx skills add https://github.com/darkmatter/skills --skill nix-flake-organization

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps refactor crowded Nix flake repositories into a cleaner structure where the public flake surface stays minimal and the real implementation lives in feature-oriented source files.

Core Features & Use Cases

Thin Public API Layer: Keeps flake files focused on output wiring, imports, and compatibility aliases instead of build logic.
Implementation Separation: Moves package, app, module, and helper logic into src paths organized by feature rather than by output type.
Migration Guidance: Supports reorganizing flake-parts projects, NixOS modules, Home Manager modules, darwin modules, overlays, and shared utilities while preserving existing output names.
Use Case: A repository with a large flake.nix can be split into a maintainable structure without breaking downstream consumers.

Quick Start

Ask the assistant to reorganize this Nix repository so the public flake surface stays thin in flake/ and the implementation moves into src/ while preserving the current outputs.

Frequently Asked Questions about nix-flake-organization

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I refactor a large Nix flake repository without breaking downstream consumers?▼

Refactoring a large Nix flake repository requires splitting implementation logic into feature-oriented src paths while keeping flake files as thin re-export layers. This preserves public output names and keeps downstream consumers unaffected during the migration.

What is the best way to organize NixOS and Home Manager modules in a flake?▼

The best way to organize NixOS and Home Manager modules is moving them into feature-oriented src paths rather than grouping by output type. This maintains a thin public API layer in flake files for imports and compatibility aliases, separating build logic from wiring.

Can I use flake-parts to split a crowded flake.nix into a maintainable structure?▼

Yes, flake-parts repositories can be reorganized into a thin public API and implementation split. This migration moves package, app, and module logic into dedicated src paths while keeping the flake.nix file focused solely on output wiring and compatibility aliases.

How do I validate that a Nix flake reorganization preserved its outputs?▼

Validate a Nix flake reorganization by running nix flake show and nix flake check after moving logic into src paths. These commands confirm that the thin re-export layer successfully preserves the original public output names and functionality.

Does refactoring Nix flake layouts into src paths work for overlays and shared helper code?▼

Yes, refactoring Nix flake layouts into src paths applies to overlays, packages, apps, and shared helper code. The implementation separation moves all build logic out of the flake files, which are kept as thin re-export layers for a minimal public surface.