Ge Song
8d704cf406
Add the Bluecraft Agentic Docs skill with guidance for maintaining root `AGENTS.md` files and `agent-docs/` trees. Include OpenAI agent metadata plus reference templates and checklists for root routing, rule docs, inventory docs, and refactor validation.
57 lines
1.8 KiB
Markdown
57 lines
1.8 KiB
Markdown
# Routing Patterns
|
|
|
|
## Preferred Patterns
|
|
|
|
### Root -> Topic Docs
|
|
|
|
Use when the repository has a small set of clearly separate instruction topics.
|
|
|
|
```md
|
|
# Required Instructions 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 can route to 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 routing 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 routing 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 route 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
|
|
|
|
## Routing 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 path from the root `AGENTS.md` to that document.
|
|
|
|
The root `AGENTS.md` should route only to the next instruction documents that are actually needed. Do not add unnecessary next-step links just for completeness.
|