Ge Song
0987c0bf0e
Restructure SKILL.md with clear triage workflow and reference selection guide. Add dedicated linking-patterns.md reference with preferred patterns and anti-patterns. Update root-agents-template.md and refactor-checklist.md to match new structure. Expand agent interface description to include refactoring and cleanup scope.
1.9 KiB
Linking Patterns
Preferred Patterns
Root -> Topic Docs
Use when the repository has a small set of clearly separate instruction topics.
# 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.
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.
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.