split agent-docs skills

skills/agent-docs/references/linking-patterns.md

@@ -0,0 +1,62 @@
+# Linking Patterns
+
+## Preferred Patterns
+
+### Root -> Topic Docs
+
+Use when the repository has a small set of clearly separate instruction topics.
+
+```md
+# Required `agent-docs` Before Editing
+
+- Read and follow `agent-docs/topic-a.md` when ...
+- Read and follow `agent-docs/topic-b.md` when ...
+```
+
+### Root -> Project Doc -> Leaf Docs
+
+Use only when the intermediate layer reduces ambiguity or repeated cross-reference text.
+
+```md
+AGENTS.md
+  -> agent-docs/project-guidelines.md
+      -> agent-docs/topic-a.md
+      -> agent-docs/topic-b.md
+```
+
+### Root -> Subproject `agent-docs/`
+
+Use in monorepos when a subproject has its own scoped instruction set.
+
+```md
+AGENTS.md
+  -> apps/docs/agent-docs/project-guidelines.md
+  -> services/api/agent-docs/backend-guidelines.md
+```
+
+Common rules stay in the root `AGENTS.md`. Subproject-specific rules stay near the subproject they govern.
+
+## Anti-Patterns
+
+- Root file linking to every leaf doc in a large tree without grouping
+- Child docs that are never reachable from the root
+- Topic-specific rules stored in the root file without a reference reason
+- Extra index files that only restate links without adding scope or decision logic
+- Moving rules out of the root file without leaving an explicit reference to the new child file
+- Keeping monorepo-wide and subproject-specific constraints mixed together in the same root section when they can be separated cleanly
+
+## Explicit Reference Rule
+
+Parent documents should point to the child documents that refine them.
+
+If a child document exists and is active, there must be an explicit reference path from the root `AGENTS.md` to that document.
+
+The root `AGENTS.md` should list only the next `agent-docs` documents that are actually needed. Do not add unnecessary next-step links just for completeness.
+
+## Conflict Resolution Rule
+
+- More specific scope beats broader scope.
+- A child doc with explicit task scope beats a generic note in the root file.
+- A rule doc's behavior rule beats an inventory entry's shorthand wording.
+- If two active docs both read like authoritative owners for the same rule, do not improvise a priority. Treat it as duplicate authority and refactor the tree.
+- If two sibling docs are equally specific and both explicitly apply, do not break the tie by tone or wording. Report the ambiguity and refactor the tree.