Ge Song
3bf898afab
Update skill definition and templates to use "references" instead of "routing" throughout, clarify the root AGENTS.md as the entry document for agent-docs, and add explicit linking patterns guidance. Improve template wording to emphasize directional, explicit references and minimal reference depth. - Rename and expand linking patterns reference - Update SKILL.md trigger conditions and core rules - Refine child doc template compatibility note - Update refactor checklist to focus on reference depth - Simplify root AGENTS.md template structure
57 lines
1.9 KiB
Markdown
57 lines
1.9 KiB
Markdown
# `agent-docs` Linking Patterns
|
|
|
|
## Preferred Patterns
|
|
|
|
### Root -> Topic Docs
|
|
|
|
Use when the repository has a small set of clearly separate instruction topics.
|
|
|
|
```md
|
|
# Read 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 when one project-specific document should explicitly reference several closely related leaf docs.
|
|
|
|
```md
|
|
AGENTS.md
|
|
-> agent-docs/project-guidelines.md
|
|
-> agent-docs/topic-a.md
|
|
-> agent-docs/topic-b.md
|
|
```
|
|
|
|
Use this only when the intermediate layer reduces ambiguity or repeated cross-reference text.
|
|
|
|
### 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.
|