feat(bluecraft-agentic-docs): add agentic docs skill templates
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.
This commit is contained in:
56
skills/bluecraft-agentic-docs/references/routing-patterns.md
Normal file
56
skills/bluecraft-agentic-docs/references/routing-patterns.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user