docs(bluecraft-agentic-docs): document explicit linking patterns and update skill rules

Add dedicated reference for root AGENTS.md to agent-docs linking patterns with
anti-patterns and explicit reference requirements. Update SKILL.md core rules to
emphasize directional, explicit references and minimal reference depth. Refine
template structures in inventory-doc-template.md and root-agents-template.md to
enforce clearer scope sections and required reading lists. Update agent interface
metadata to reflect focused maintenance scope.

skills/bluecraft-agentic-docs/SKILL.md

@@ -3,13 +3,13 @@ name: bluecraft-agentic-docs
 description: Use when creating, updating, splitting, merging, reviewing, auditing, or deleting the AGENTS.md at the root of the current Git working tree, or Markdown files inside any agent-docs/ directory
 ---
 
-# Agentic Docs
+# Maintain AGENTS.md and agent-docs
 
 ## Overview
 
-Use this skill to maintain agent-facing documentation trees centered on the `AGENTS.md` at the root of the current Git working tree and the applicable `agent-docs/` documents.
+Use this skill to maintain the root `AGENTS.md` file and the applicable `agent-docs/` files in the current Git working tree.
 
-Treat covered documents as instruction documents. If one applies in scope, it must be followed, not treated as optional background reading.
+Treat covered files as required instructions. If one applies in scope, it must be followed, not treated as optional background reading.
 
 ## When To Use
 
@@ -18,9 +18,9 @@ Use this skill when a task involves any of the following:
 - creating or editing the `AGENTS.md` at the root of the current Git working tree
 - creating, editing, splitting, merging, or deleting Markdown files inside any `agent-docs/` directory
 - changing explicit references between `AGENTS.md` and `agent-docs/` files
-- auditing whether an agentic documentation tree is coherent, minimal, and fully connected
+- auditing whether `AGENTS.md` and `agent-docs/` stay coherent, minimal, and fully connected
 
-Do not use this skill for end-user documentation, product manuals, README content that is not part of the agentic documentation tree, or project-specific business rules that do not govern agent-facing docs.
+Do not use this skill for end-user documentation, product manuals, README content that is not part of `AGENTS.md` or `agent-docs/`, or project-specific business rules that do not govern agent-facing docs.
 
 ## Core Rules
 
@@ -33,33 +33,48 @@ Do not use this skill for end-user documentation, product manuals, README conten
 - When referencing repository files from `AGENTS.md` or `agent-docs/`, prefer plain repository-relative paths in backticks such as `agent-docs/example.md`, not Markdown links.
 - Do not embed machine-local absolute filesystem paths such as `/home/...`.
 - Do not mix general agentic-documentation rules with project-specific business rules, product instructions, media planning, or end-user documentation guidance in the same general-purpose file.
-- Treat the `AGENTS.md` at the root of the current Git working tree as the root entry document for the repository's `agent-docs`.
 - Keep common, repository-wide constraints in that root `AGENTS.md`.
 - In monorepos, keep common constraints in the root `AGENTS.md` and place subproject-specific constraints in the relevant `agent-docs/` directory near that subproject.
 - Put project-specific or topic-specific constraints in the relevant child documents under `agent-docs/`.
-- The root `AGENTS.md` should reference only the `agent-docs` documents that are actually required for the next editing decision.
-- The combined set of the root `AGENTS.md` and active `agent-docs/` files should form a connected documentation tree.
-- Each active instruction document must be reachable through explicit references from the root entrypoint.
-- Do not leave orphan instruction documents.
+- Treat the `AGENTS.md` at the root of the current Git working tree as the starting point for required `agent-docs`.
+- Keep `AGENTS.md` focused on the next reading decision: reference only the `agent-docs` files that are actually needed.
 - Keep one authoritative home for each rule; link instead of duplicating.
 - When a file, path, or rule is obsolete, remove or update it in the same change instead of leaving stale references behind.
+- Delete or update any `agent-docs` file that is no longer referenced from the root `AGENTS.md`.
 - Prefer stable, semantic filenames.
 - Unless a specific instruction explicitly defines another base path, treat every path mentioned in the conversation or in agentic documentation as relative to the root of the current Git working tree, not relative to the current file.
 - Keep references directional and explicit: a parent document should point to the child documents that refine it.
+- Every active `agent-docs` file must still be reachable from the root `AGENTS.md`.
 - Match the child document shape to the document's job. Do not force inventory or registry documents into the same structure as rule or policy documents.
 
 ## Workflow
 
-1. Identify the change type.
+1. Identify the files and scope.
 
-Choose the smallest accurate category:
+Start with the concrete files and scope that need to change:
 
-- root entry or cross-reference change
-- repository-wide constraint change
-- child instruction document change
+- root `AGENTS.md`
+- one or more `agent-docs/` files
+- both root and child files
 - documentation-tree refactor
 
-2. Identify the child document type.
+2. Decide where the rule should live.
+
+- Root `AGENTS.md`: root entry document and repository-wide constraints
+- `agent-docs/` child docs: scoped instructions for a topic, project area, or workflow
+
+If a rule only matters within one child topic, do not keep it in the root file.
+
+3. Update explicit references.
+
+- Add or adjust references from the root file to the necessary child files.
+- If a child file introduces narrower subtopics, point to them explicitly.
+- Avoid extra reference layers unless they materially reduce ambiguity.
+- When moving project-specific constraints out of the root `AGENTS.md`, replace them with an explicit reference to the new child document instead of leaving the reference implicit.
+
+See `references/how-to-link-root-agents-and-agent-docs.md` for reference patterns and anti-patterns.
+
+4. Pick the document shape.
 
 Use the smallest fitting type:
 
@@ -69,24 +84,6 @@ Use the smallest fitting type:
 
 If a document spends most of its space enumerating items to maintain, do not force it into the rule-doc shape.
 
-3. Decide rule placement.
-
-Use this placement standard:
-
-- Root `AGENTS.md`: root entry document and repository-wide constraints
-- `agent-docs/` child docs: scoped instructions for a topic, project area, or workflow
-
-If a rule only matters within one child topic, do not keep it in the root file.
-
-4. Update explicit references.
-
-- Add or adjust references from the root file to the necessary child files.
-- If a child file introduces narrower subtopics, point to them explicitly.
-- Avoid extra reference layers unless they materially reduce ambiguity.
-- When moving project-specific constraints out of the root `AGENTS.md`, replace them with an explicit reference to the new child document instead of leaving the reference implicit.
-
-See `references/agent-docs-linking-patterns.md` for reference patterns and anti-patterns.
-
 5. Remove stale structure.
 
 - Delete obsolete files, references, and filenames in the same change.
@@ -106,7 +103,7 @@ Adapt the wording to the repository, but preserve the explicit-reference and sco
 
 7. Verify.
 
-- Check that the root `AGENTS.md` still acts as the primary entrypoint.
+- Check that the root `AGENTS.md` still acts as the starting point for required `agent-docs`.
 - Check that every active child doc is reachable from the root through explicit references.
 - Check that no rule is duplicated across multiple active files without a clear reason.
 - Check that rule docs and inventory docs are not mixed together without a clear reason.
@@ -120,7 +117,7 @@ Use `references/refactor-checklist.md` as the final pass.
 - Rule child template: `references/rule-doc-template.md`
 - Inventory child template: `references/inventory-doc-template.md`
 - Child template chooser: `references/child-doc-template.md`
-- Linking patterns: `references/agent-docs-linking-patterns.md`
+- Linking patterns: `references/how-to-link-root-agents-and-agent-docs.md`
 - Refactor checklist: `references/refactor-checklist.md`
 
 Read only the reference files needed for the current task.
@@ -130,7 +127,7 @@ Read only the reference files needed for the current task.
 - Does each covered document own one clear topic?
 - Does the filename clearly express the document's purpose?
 - Does the opening explain the document's purpose, trigger, and in-scope follow requirement?
-- Is the `AGENTS.md` at the root of the current Git working tree still the root entry document?
+- Is the `AGENTS.md` at the root of the current Git working tree still the starting point for required `agent-docs`?
 - Is every active `agent-docs/` file reachable from the root through explicit references?
 - Are obsolete paths, filenames, and documents removed?
 - Were obsolete index layers removed?

skills/bluecraft-agentic-docs/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "Bluecraft Agentic Docs"
-  short_description: "Maintain AGENTS.md and agent-docs trees"
-  default_prompt: "Use $bluecraft-agentic-docs to maintain the AGENTS.md and agent-docs documentation tree."
+  display_name: "Maintain AGENTS.md and agent-docs"
+  short_description: "Maintain AGENTS.md and agent-docs instructions"
+  default_prompt: "Use $bluecraft-agentic-docs to maintain AGENTS.md and agent-docs instructions."

skills/bluecraft-agentic-docs/references/how-to-link-root-agents-and-agent-docs.md

@@ -1,4 +1,4 @@
-# `agent-docs` Linking Patterns
+# How To Link Root AGENTS.md And agent-docs
 
 ## Preferred Patterns
 
@@ -7,7 +7,7 @@
 Use when the repository has a small set of clearly separate instruction topics.
 
 ```md
-# Read Required `agent-docs` Before Editing
+# Required `agent-docs` Before Editing
 
 - Read and follow `agent-docs/topic-a.md` when ...
 - Read and follow `agent-docs/topic-b.md` when ...

skills/bluecraft-agentic-docs/references/inventory-doc-template.md

@@ -9,11 +9,11 @@ Use this structure for Markdown files inside `agent-docs/` when the document's m
 
 <Opening statement: what this inventory tracks, when it should be used or updated, and that it must be followed in scope.>
 
-## Use This For
+## Applies To
 
 - <tasks that require reading or updating this inventory>
 
-## Do Not Use This For
+## Does Not Apply To
 
 - <tasks that belong in a rule doc, public docs, or another inventory>
 

skills/bluecraft-agentic-docs/references/root-agents-template.md

@@ -15,7 +15,7 @@ Use this structure for the `AGENTS.md` at the root of the current Git working tr
 - Keep repository-wide rules here.
 - Do not repeat topic-specific rules that belong in child docs.
 
-# Read Required `agent-docs` Before Editing
+# Required `agent-docs` Before Editing
 
 - List the required `agent-docs` explicitly.
 - Use explicit "Read and follow ..." wording.