Add agent skills
This commit is contained in:
134
.agents/skills/nixos-best-practices/SKILL.md
Normal file
134
.agents/skills/nixos-best-practices/SKILL.md
Normal file
@@ -0,0 +1,134 @@
|
||||
---
|
||||
name: nixos-best-practices
|
||||
description: Use when configuring NixOS with flakes, managing overlays with home-manager useGlobalPkgs, structuring NixOS configurations, or facing issues where configuration changes don't apply
|
||||
license: MIT
|
||||
metadata:
|
||||
author: chumeng
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Configuring NixOS Systems with Flakes
|
||||
|
||||
Configure NixOS systems with flakes, manage overlays properly, and structure configurations for maintainability.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Understand the interaction between NixOS system configuration and Home Manager overlays.**
|
||||
|
||||
When `useGlobalPkgs = true`, overlays must be defined at the NixOS configuration level, not in Home Manager configuration files.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Configuring NixOS with flakes and Home Manager
|
||||
- Adding overlays that don't seem to apply
|
||||
- Using `useGlobalPkgs = true` with custom overlays
|
||||
- Structuring NixOS configurations across multiple hosts
|
||||
- Package changes not appearing after rebuild
|
||||
- Confused about where to define overlays
|
||||
|
||||
**Don't use for:**
|
||||
- Packaging new software (use nix-packaging-best-practices)
|
||||
- Simple package installation without overlays
|
||||
- NixOS module development (see NixOS module documentation)
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Topic | Rule File |
|
||||
|-------|-----------|
|
||||
| Overlay scope and useGlobalPkgs | [overlay-scope](rules/overlay-scope.md) |
|
||||
| Flakes configuration structure | [flakes-structure](rules/flakes-structure.md) |
|
||||
| Host configuration organization | [host-organization](rules/host-organization.md) |
|
||||
| Package installation best practices | [package-installation](rules/package-installation.md) |
|
||||
| Common configuration mistakes | [common-mistakes](rules/common-mistakes.md) |
|
||||
| Debugging configuration issues | [troubleshooting](rules/troubleshooting.md) |
|
||||
|
||||
## Essential Pattern: Overlay with useGlobalPkgs
|
||||
|
||||
```nix
|
||||
# ❌ WRONG: Overlay in home.nix (doesn't apply)
|
||||
# home-manager/home.nix
|
||||
{
|
||||
nixpkgs.overlays = [ inputs.claude-code.overlays.default ]; # Ignored!
|
||||
home.packages = with pkgs; [ claude-code ]; # Not found!
|
||||
}
|
||||
|
||||
# ✅ CORRECT: Overlay in NixOS home-manager block
|
||||
# hosts/home/default.nix
|
||||
{
|
||||
home-manager.useGlobalPkgs = true;
|
||||
home-manager.useUserPackages = true;
|
||||
home-manager.users.chumeng = import ./home.nix;
|
||||
home-manager.extraSpecialArgs = { inherit inputs pkgs-stable system; };
|
||||
# Overlay must be HERE when useGlobalPkgs = true
|
||||
nixpkgs.overlays = [ inputs.claude-code.overlays.default ];
|
||||
}
|
||||
```
|
||||
|
||||
## Common Tasks
|
||||
|
||||
| Task | Solution |
|
||||
|------|----------|
|
||||
| Add flake input | Add to `inputs` in flake.nix |
|
||||
| Add overlay for system packages | Define in `nixpkgs.overlays` in system configuration |
|
||||
| Add overlay for home-manager (useGlobalPkgs=true) | Define in `home-manager.nixpkgs.overlays` in host config |
|
||||
| Add overlay for home-manager (useGlobalPkgs=false) | Define in `home.nix` with `nixpkgs.overlays` |
|
||||
| Pass inputs to modules | Use `specialArgs` in nixosSystem or home-manager |
|
||||
| Multiple host configurations | Create separate host files in `hosts/` |
|
||||
| Shared configuration modules | Create modules in `modules/` and import in each host |
|
||||
| Package not found after overlay | Check overlay scope vs useGlobalPkgs setting |
|
||||
|
||||
## Overlay Scope Decision Matrix
|
||||
|
||||
| useGlobalPkgs | Overlay Definition Location | Affects |
|
||||
|---------------|---------------------------|---------|
|
||||
| `true` | `home-manager.nixpkgs.overlays` | System + Home Manager packages |
|
||||
| `true` | `home.nix` with `nixpkgs.overlays` | **Nothing** (ignored!) |
|
||||
| `false` | `home.nix` with `nixpkgs.overlays` | Home Manager packages only |
|
||||
| `false` | `home-manager.nixpkgs.overlays` | Home Manager packages only |
|
||||
| Any | System `nixpkgs.overlays` | System packages only |
|
||||
|
||||
## Configuration Layers (Bottom to Top)
|
||||
|
||||
1. **System configuration** (`/etc/nixos/configuration.nix` or host files)
|
||||
- System-wide services
|
||||
- System packages
|
||||
- System overlays only affect this layer
|
||||
|
||||
2. **Home Manager (useGlobalPkgs=true)**
|
||||
- Uses system pkgs (includes system overlays)
|
||||
- Home Manager overlays affect both system and user packages
|
||||
- Most efficient for single-user systems
|
||||
|
||||
3. **Home Manager (useGlobalPkgs=false)**
|
||||
- Creates separate pkgs instance
|
||||
- Home Manager overlays affect user packages only
|
||||
- Useful for multi-user systems with different needs
|
||||
|
||||
## Red Flags - STOP
|
||||
|
||||
- "Overlay in home.nix isn't working" → Check if useGlobalPkgs=true, move to host config
|
||||
- "I'll just add overlays everywhere" → Define once at appropriate scope
|
||||
- "Package works in nix repl but not installed" → Check overlay scope
|
||||
- "Changes don't apply after rebuild" → Verify overlay is in correct location
|
||||
- "useGlobalPkgs=false for no reason" → Use true unless you need separate package sets
|
||||
|
||||
## How to Use
|
||||
|
||||
Read individual rule files for detailed explanations and code examples:
|
||||
|
||||
```
|
||||
rules/overlay-scope.md # The core overlay scope issue
|
||||
rules/flakes-structure.md # How to organize flake.nix
|
||||
rules/host-organization.md # How to structure host configs
|
||||
rules/common-mistakes.md # Pitfalls and how to avoid them
|
||||
```
|
||||
|
||||
Each rule file contains:
|
||||
- Brief explanation of why it matters
|
||||
- Incorrect code example with explanation
|
||||
- Correct code example with explanation
|
||||
- Additional context and references
|
||||
|
||||
## Full Compiled Document
|
||||
|
||||
For the complete guide with all rules expanded: `AGENTS.md`
|
||||
Reference in New Issue
Block a user