refactor(bluecraft-agentic-docs): reorganize skill documentation and create linking patterns reference

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.

skills/bluecraft-agentic-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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
+description: Use when creating, updating, splitting, merging, reviewing, auditing, deleting, or refactoring the root AGENTS.md or agent-docs files, especially when cross-references, child docs, or orphan docs may need cleanup
 ---
 
 # Maintain AGENTS.md and agent-docs
@@ -22,32 +22,7 @@ Use this skill when a task involves any of the following:
 
 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
-
-- Each covered document should own one clear topic.
-- Titles and filenames should state purpose directly.
-- The opening section should explain what the document governs, when it applies, and that it must be followed in scope.
-- Rules should be actionable, not slogan-like.
-- Prefer standard Markdown headings and lists over wrapper tags for structure.
-- Write for maintainers. State actions, constraints, and decision criteria directly.
-- 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.
-- 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/`.
-- 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
+## Quick Triage
 
 1. Identify the files and scope.
 
@@ -58,58 +33,68 @@ Start with the concrete files and scope that need to change:
 - both root and child files
 - documentation-tree refactor
 
-2. Decide where the rule should live.
+## Which Reference To Read
 
-- Root `AGENTS.md`: root entry document and repository-wide constraints
-- `agent-docs/` child docs: scoped instructions for a topic, project area, or workflow
+- Root `AGENTS.md` update: read `references/root-agents-template.md`.
+- Child rule or policy doc: read `references/rule-doc-template.md`.
+- Child inventory or registry doc: read `references/inventory-doc-template.md`.
+- Unsure whether a child doc is a rule doc or inventory doc: read `references/child-doc-template.md`.
+- Cross-reference or document-tree change: read `references/linking-patterns.md`.
 
-If a rule only matters within one child topic, do not keep it in the root file.
+## Core Constraints
 
-3. Update explicit references.
+- Each covered document should own one clear topic.
+- Titles and filenames should state purpose directly.
+- The opening section should explain what the document governs, when it applies, and that it must be followed in scope.
+- Rules should be actionable, not slogan-like.
+- Prefer standard Markdown headings and lists over wrapper tags for structure.
+- Write for maintainers. State actions, constraints, and decision criteria directly.
+- 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.
+- Keep common, repository-wide constraints in the 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/`.
+- Treat the root `AGENTS.md` 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 the docs 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.
 
-- 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.
+## Common Mistakes
 
-See `references/how-to-link-root-agents-and-agent-docs.md` for reference patterns and anti-patterns.
+- Putting topic-specific rules in the root `AGENTS.md` when they belong in one child doc.
+- Adding a new `agent-docs` file without adding an explicit reference path from the root `AGENTS.md`.
+- Repeating the same rule in multiple active files instead of linking to one authoritative source.
+- Splitting a document only for symmetry, without reducing ambiguity or maintenance cost.
+- Forcing a maintained list into a rule-doc shape instead of using an inventory doc.
 
-4. Pick the document shape.
+## When Not To Split
 
-Use the smallest fitting type:
+- Do not split when one short document already governs one clear topic.
+- Do not add an intermediate file that only repeats links without adding scope or decision logic.
+- Do not create a new child doc when it would not reduce ambiguity, repetition, or maintenance cost.
 
-- rule doc: instructions, constraints, decision rules, policy, or workflow guidance
-- inventory doc: maintained list, registry, media plan, page-by-page backlog, or cleanup queue
-- hybrid doc: only when one short inventory is inseparable from the governing rules; otherwise split it
+## Verification
 
-If a document spends most of its space enumerating items to maintain, do not force it into the rule-doc shape.
-
-5. Remove stale structure.
-
-- Delete obsolete files, references, and filenames in the same change.
-- If a split removes the need for an intermediate layer, remove that layer.
-- If a new file is added, ensure it is reachable from the root entrypoint.
-
-6. Apply the standard document shape.
-
-- For a root file update, use `references/root-agents-template.md`.
-- For a rule or policy child doc, use `references/rule-doc-template.md`.
-- For an inventory or registry child doc, use `references/inventory-doc-template.md`.
-- Use `references/child-doc-template.md` only as the compatibility entrypoint when you need help choosing between child templates.
-- Use standard Markdown headings and lists unless a narrower instruction requires another structure.
-- Treat inventory entry fields as a recommended starter shape, not a fixed schema. Keep only the fields that materially help maintainers scan and update the inventory.
-
-Adapt the wording to the repository, but preserve the explicit-reference and scope model.
-
-7. Verify.
-
-- Check that the root `AGENTS.md` still acts as the starting point for required `agent-docs`.
+- Read `references/refactor-checklist.md` as the final pass.
+- Check that the root `AGENTS.md` is still 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.
 - Run the validation command actually used by the repository if the change affects rendered documentation or project checks.
 
-Use `references/refactor-checklist.md` as the final pass.
+## Validation Steps
+
+- Confirm `agents/openai.yaml` still matches the skill title, scope, and trigger language.
+- Confirm every file in `references/` is directly referenced from this `SKILL.md`.
+- Confirm there are no stale filenames or old terms left behind after renames.
+- Confirm one concept still uses one term across `SKILL.md` and `references/`.
 
 ## Templates And References
 
@@ -117,7 +102,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/how-to-link-root-agents-and-agent-docs.md`
+- Linking patterns: `references/linking-patterns.md`
 - Refactor checklist: `references/refactor-checklist.md`
 
 Read only the reference files needed for the current task.