diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 387c300..6259daa 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,3 +13,9 @@ zig fmt .
 ```
 
 CI runs `zig fmt --check .` and will fail on unformatted code.
+
+## agent skills
+
+`.agents/skills/` is the canonical skills directory (the cross-tool location
+read by codex, gemini, and others). `.claude/skills` is a symlink to it for
+claude code, which only reads its vendor path — edit skills in `.agents/`.