From e460aa2b57fae13240003a90d1094700b416d972 Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Wed, 16 Sep 2026 11:06:26 -0400
Subject: [PATCH] docs(skills): define nix rule format

---
 src/skills/nix-style/SKILL.md       | 20 +++++++++++++++++++-
 src/skills/nix-style/rules/flake.md |  4 ++++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/src/skills/nix-style/SKILL.md b/src/skills/nix-style/SKILL.md
index 196d6e0..6ed7e63 100644
--- a/src/skills/nix-style/SKILL.md
+++ b/src/skills/nix-style/SKILL.md
@@ -18,10 +18,28 @@ find src/skills/nix-style/rules -maxdepth 1 -type f -name '*.md' -print | sort
 
 Finish when all discovered rule files have been read.
 
+## Write rules
+
+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.
+
 ## Apply rules
 
 Apply the loaded rules when editing or reviewing Nix files.
-Prefer the most specific rule when two rules cover the same code.
+When loaded rules conflict, follow the most specific rule.
 
 After editing Nix files, run:
 
diff --git a/src/skills/nix-style/rules/flake.md b/src/skills/nix-style/rules/flake.md
index 7a94f04..038541d 100644
--- a/src/skills/nix-style/rules/flake.md
+++ b/src/skills/nix-style/rules/flake.md
@@ -2,8 +2,12 @@
 
 ## 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.