From 8154feba5ac06c96e5e62d657a427de5961ed2c1 Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Wed, 16 Sep 2026 11:27:24 -0400
Subject: [PATCH] feat(skills): add nix style guidance

---
 .pi/prompts/review-nix.md           | 21 ++++++++++++++++
 .pi/skills/nix-style                |  1 +
 src/skills/nix-style/RULE-FORMAT.md | 17 +++++++++++++
 src/skills/nix-style/SKILL.md       | 37 +++++++++++++++++++++++++++++
 src/skills/nix-style/rules/flake.md | 13 ++++++++++
 5 files changed, 89 insertions(+)
 create mode 100644 .pi/prompts/review-nix.md
 create mode 120000 .pi/skills/nix-style
 create mode 100644 src/skills/nix-style/RULE-FORMAT.md
 create mode 100644 src/skills/nix-style/SKILL.md
 create mode 100644 src/skills/nix-style/rules/flake.md

diff --git a/.pi/prompts/review-nix.md b/.pi/prompts/review-nix.md
new file mode 100644
index 0000000..fdf09c1
--- /dev/null
+++ b/.pi/prompts/review-nix.md
@@ -0,0 +1,21 @@
+---
+description: Review Nix changes against repository Nix style rules
+argument-hint: "[target]"
+---
+
+Use the `nix-style` skill.
+Audit ${ARGUMENTS:-the staged diff} for violations of the repository Nix style rules.
+
+Report only actionable findings.
+Order findings by severity.
+Do not report preferences unless a loaded rule states them.
+
+Use this format for each finding:
+
+```text
+`path:line`: Finding title.
+Summary: why the code breaks the rule
+Fix: suggested fix
+```
+
+It is acceptable to report no findings when the reviewed Nix already follows the loaded rules.
diff --git a/.pi/skills/nix-style b/.pi/skills/nix-style
new file mode 120000
index 0000000..1622f88
--- /dev/null
+++ b/.pi/skills/nix-style
@@ -0,0 +1 @@
+../../src/skills/nix-style
\ No newline at end of file
diff --git a/src/skills/nix-style/RULE-FORMAT.md b/src/skills/nix-style/RULE-FORMAT.md
new file mode 100644
index 0000000..8abe570
--- /dev/null
+++ b/src/skills/nix-style/RULE-FORMAT.md
@@ -0,0 +1,17 @@
+# Rule format
+
+Use this structure for each rule:
+
+```md
+## Rule title
+
+### Rule
+
+State enforceable instructions.
+
+### Rationale
+
+Explain why the rule exists.
+```
+
+Add `### Examples` only when examples clarify the rule.
diff --git a/src/skills/nix-style/SKILL.md b/src/skills/nix-style/SKILL.md
new file mode 100644
index 0000000..805c6bc
--- /dev/null
+++ b/src/skills/nix-style/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: nix-style
+description: Use when creating, editing, or reviewing Nix files in this repository.
+---
+
+# nix-style
+
+Use this skill as the source of truth for repository Nix conventions.
+
+## Load rules
+
+Read every Markdown file under [`rules/`](rules/) before applying this skill.
+Discover rule files from the skill source:
+
+```bash
+find src/skills/nix-style/rules -maxdepth 1 -type f -name '*.md' -print | sort
+```
+
+Finish when all discovered rule files have been read.
+
+## Apply rules
+
+Apply the loaded rules when editing or reviewing Nix files.
+When loaded rules conflict, follow the most specific rule.
+
+After editing Nix files, run:
+
+```bash
+nix run .#fix
+```
+
+Finish when the Nix change follows the loaded rules.
+
+## Maintain rules
+
+When adding or changing files under [`rules/`](rules/), read [`RULE-FORMAT.md`](RULE-FORMAT.md) first.
+Finish when the changed rule files follow that format.
diff --git a/src/skills/nix-style/rules/flake.md b/src/skills/nix-style/rules/flake.md
new file mode 100644
index 0000000..038541d
--- /dev/null
+++ b/src/skills/nix-style/rules/flake.md
@@ -0,0 +1,13 @@
+# Flake rules
+
+## Keep `flake.nix` as flake wiring
+
+### Rule
+
+Add flake inputs in `flake.nix`.
+Put new flake output implementation in `src/dotfiles/default.nix`.
+Use `flake.nix` to pass inputs into that implementation.
+
+### Rationale
+
+This keeps dependency declarations separate from output logic.
-- 
2.47.3