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.
1.8 KiB
Routing Patterns
Preferred Patterns
Root -> Topic Docs
Use when the repository has a small set of clearly separate instruction topics.
# 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.
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.
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.