Skip to content

Commit 053b405

Browse files
r17xclaude
andcommitted
feat(agent): add nix development skills for Claude Code
Add comprehensive Nix skills to enhance Claude's assistance with: Skills created: - /nix: Main skill for flakes, darwin, NixOS, home-manager - /nix-debug: Deep debugging (eval, repl, trace, debugger) - /nix-flake: Flake evaluation and introspection - /nix-module: Module development patterns - /nix-service: launchd/systemd service management Includes: - Complete nix eval/repl command reference - lib.debug.* function cookbook (traceVal, traceSeq, etc.) - Interactive debugger (Nix 2.9+) guide - Error diagnosis patterns with solutions - Module system debugging techniques - Platform-specific patterns (Darwin/Linux) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 8b568e7 commit 053b405

File tree

5 files changed

+816
-0
lines changed

5 files changed

+816
-0
lines changed

.claude/skills/nix/SKILL.md

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
name: nix
3+
description: Nix flakes, nix-darwin, NixOS, and home-manager development assistance
4+
allowed-tools:
5+
- Bash
6+
- Read
7+
- Grep
8+
- Glob
9+
- Edit
10+
- Write
11+
---
12+
13+
# Nix Development Skill
14+
15+
## Evaluation & Debugging
16+
17+
### Evaluate flake outputs
18+
```bash
19+
# List available outputs
20+
nix flake show
21+
22+
# Evaluate specific attribute
23+
nix eval .#<attribute> --json
24+
25+
# Darwin config options
26+
nix eval .#darwinConfigurations.<host>.options.<path>
27+
28+
# Home-manager config
29+
nix eval .#homeConfigurations."<user>@<host>".config.<path>
30+
```
31+
32+
### Debug evaluation errors
33+
```bash
34+
# Show full trace
35+
nix eval .#<attr> --show-trace
36+
37+
# Check flake validity
38+
nix flake check
39+
40+
# Instantiate without building
41+
nix-instantiate --eval -E '<expression>'
42+
```
43+
44+
## Building & Rebuilding
45+
46+
### Darwin (macOS)
47+
```bash
48+
darwin-rebuild switch --flake .
49+
darwin-rebuild switch --flake .#<hostname>
50+
51+
# Rollback
52+
darwin-rebuild --list-generations
53+
darwin-rebuild switch --rollback
54+
```
55+
56+
### NixOS
57+
```bash
58+
sudo nixos-rebuild switch --flake .#<hostname>
59+
sudo nixos-rebuild boot --flake .#<hostname>
60+
```
61+
62+
### Home-manager standalone
63+
```bash
64+
home-manager switch --flake .#<user>@<host>
65+
```
66+
67+
## Service Management (launchd/systemd)
68+
69+
### macOS launchd
70+
```bash
71+
# List services
72+
launchctl list | grep -E "org.nixos|nix"
73+
74+
# Service status
75+
launchctl print system/<label>
76+
launchctl print gui/$(id -u)/<label>
77+
78+
# Control services
79+
launchctl kickstart [-k] <domain>/<label>
80+
launchctl kill SIGTERM <domain>/<label>
81+
```
82+
83+
### Linux systemd
84+
```bash
85+
systemctl --user list-units --type=service
86+
systemctl --user status <service>
87+
systemctl --user restart <service>
88+
journalctl --user -u <service> -f
89+
```
90+
91+
## Launchd Configuration Options
92+
93+
For reducing CPU/IO priority in nix-darwin:
94+
```nix
95+
launchd.daemons.<name>.serviceConfig = {
96+
RunAtLoad = false; # Don't start at boot
97+
KeepAlive = false; # Don't auto-restart
98+
Nice = 5; # Lower CPU priority (1-20)
99+
ProcessType = "Background"; # Background scheduling
100+
LowPriorityIO = true; # Lower I/O priority
101+
ThrottleInterval = 10; # Min seconds between restarts
102+
};
103+
104+
launchd.user.agents.<name>.serviceConfig = { /* same options */ };
105+
```
106+
107+
## Common Patterns
108+
109+
### Override with mkForce
110+
```nix
111+
# When upstream sets a value you need to override
112+
someOption = lib.mkForce false;
113+
```
114+
115+
### Conditional by platform
116+
```nix
117+
# At Nix level (preferred)
118+
serviceCommands = if pkgs.stdenv.isDarwin
119+
then import ./darwin.nix
120+
else import ./linux.nix;
121+
122+
# In module
123+
config = lib.mkIf pkgs.stdenv.isDarwin { ... };
124+
```
125+
126+
### Module structure
127+
```nix
128+
{ lib, config, pkgs, ... }:
129+
let
130+
cfg = config.myModule;
131+
in {
132+
options.myModule = {
133+
enable = lib.mkEnableOption "my module";
134+
};
135+
136+
config = lib.mkIf cfg.enable {
137+
# implementation
138+
};
139+
}
140+
```
141+
142+
## Flake Inputs Management
143+
144+
```bash
145+
# Update all inputs
146+
nix flake update
147+
148+
# Update specific input
149+
nix flake lock --update-input <input-name>
150+
151+
# Show inputs
152+
nix flake metadata
153+
```
154+
155+
## Troubleshooting
156+
157+
### "infinite recursion" error
158+
- Check for circular dependencies in imports
159+
- Use `lib.mkDefault` or `lib.mkForce` to resolve conflicts
160+
161+
### "attribute not found"
162+
- Verify the attribute path with `nix eval`
163+
- Check if module is properly imported
164+
165+
### Service not starting
166+
- Check plist/unit file generation
167+
- Verify paths in ProgramArguments
168+
- Check logs for errors

0 commit comments

Comments
 (0)