diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..48e410f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,23 @@
+# Agent Guidelines for NixOS Configuration
+
+## Build & Deploy Commands
+- `nix flake check` - Validate flake configuration
+- `build <host>` - Build configuration for specific host (e.g., `build radish`)
+- `apply <host>` - Deploy to remote host via colmena
+- `apply-local` - Apply configuration locally using nh
+- `nix build .#nixosConfigurations.<host>.config.system.build.toplevel` - Build specific host
+
+## Code Style
+- **Format**: Use `nixfmt-rfc-style` for all .nix files
+- **Imports**: List imports first, group by: local modules, external inputs (inputs.*)
+- **Function args**: Multi-line with trailing comma when >3 args: `{ config, lib, pkgs, ... }:`
+- **Options**: Define in `options.<service>` block, implement in `config = lib.mkIf cfg.enable { ... }`
+- **Types**: Use `lib.types.*` for option types (str, bool, int, etc.)
+- **String interpolation**: Use `"${}"` for Nix expressions, prefer lib.getExe for binaries
+- **Conditionals**: Use `lib.mkIf`, `lib.mkDefault`, `lib.mkMerge` for NixOS options
+
+## Structure
+- Host configs in `hosts/<name>/` with configuration.nix, default.nix, hardware-configuration.nix
+- Reusable modules in `modules/` and `modules/services/`
+- Custom packages in `custom-pkgs/` using util.package pattern
+- Secrets managed via agenix in `secrets/` directory