From a8464e407e7623e3b4bdef0c0c7e627a2029af80 Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Wed, 2 Sep 2026 14:40:12 -0400
Subject: [PATCH] docs(skills): document monorepo skill layout

---
 .agents/skills/.gitkeep |  0
 src/skills/AGENTS.md    |  0
 src/skills/README.md    | 36 ++++++++++++++++++++++++++++++++++++
 3 files changed, 36 insertions(+)
 create mode 100644 .agents/skills/.gitkeep
 create mode 100644 src/skills/AGENTS.md
 create mode 100644 src/skills/README.md

diff --git a/.agents/skills/.gitkeep b/.agents/skills/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/src/skills/AGENTS.md b/src/skills/AGENTS.md
new file mode 100644
index 0000000..e69de29
diff --git a/src/skills/README.md b/src/skills/README.md
new file mode 100644
index 0000000..f8c886b
--- /dev/null
+++ b/src/skills/README.md
@@ -0,0 +1,36 @@
+# Skills
+
+This directory contains monorepo-owned agent skill sources.
+
+## Layout
+
+```text
+src/skills/                         Monorepo-owned skill sources
+.agents/skills/                     Monorepo-wide enabled skill symlinks
+src/<project>/skills/               Project-owned skill sources
+src/<project>/.agents/skills/       Project-specific enabled skill symlinks
+```
+
+## Source ownership
+
+Use `src/skills/` for skills that support workflows across the monorepo.
+Keep project-specific skills inside the project that owns them.
+
+For example, a `gitea-axi` skill belongs with the `gitea-axi` project source.
+A general commit or review workflow skill belongs in `src/skills/`.
+
+## Enablement
+
+Enable skills with symlinks.
+Do not copy skill sources into `.agents/skills/`.
+
+Use root `.agents/skills/` for skills that should be available when Pi starts at the monorepo root.
+Use `src/<project>/.agents/skills/` for skills that should be available only when Pi starts in that project subtree.
+
+Pi scans `.agents/skills/` in the current working directory and ancestors up to the Git root.
+Pi does not scan descendant project directories when it starts at the monorepo root.
+
+## Distribution
+
+This monorepo optimizes for local use.
+Do not add packaging or distribution layers until a concrete distribution need exists.