diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..86eb83a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,41 @@
+# Sigil usage (for agents)
+
+This repo is managed by **Sigil**, a minimal symlink-based dotfile tool.
+
+## Repo layout
+```
+~/.dotfiles/
+  <package>/
+    config.lua
+    files/
+      ...
+```
+
+Each package has a `config.lua` that defines its target path per OS.
+
+## Common commands
+- `sigil apply` — apply symlinks (prompts for stale links)
+- `sigil apply --prune` — prune stale links without prompting
+- `sigil add <path>` — add a file/dir to the repo and symlink it
+- `sigil status` — show stale links
+- `sigil unlink <spec>` — restore file(s) to target and remove from repo
+- `sigil remove <spec>` — same as unlink, plus remove package/subpath from repo
+
+## Spec formats
+`unlink/remove` accept these:
+- `package` (entire package)
+- `package:relative/path`
+- repo path: `~/.dotfiles/<pkg>/files/...`
+- target path: e.g. `~/.config/<app>/...`
+
+Examples:
+```
+sigil unlink wezterm
+sigil unlink wezterm:lua
+sigil unlink ~/.dotfiles/wezterm/files/wezterm.lua
+sigil unlink ~/.config/wezterm/wezterm.lua
+```
+
+## Notes
+- If a repo file is missing, stale links should be pruned.
+- Prefer `sigil add` over manual moves into `files/`.