bluecraft/skills/agent-docs-refactor/SKILL.md

name, description

name	description
agent-docs-refactor	Use when creating, updating, splitting, merging, rerouting, renaming, or deleting AGENTS.md and agent-docs, especially when references, child docs, or document responsibilities must change together.

Agent Docs Refactor

Overview

Use this skill to edit the root AGENTS.md or files under agent-docs/. It is the production workflow for restructuring the document tree while preserving explicit routing and single-home rule ownership.

When to Use

• The user asks to optimize, refactor, split, merge, or rewrite AGENTS or agent-docs
• A rule must move from one document to another
• A new child doc must be introduced or an obsolete one removed
• Cross-references, routing text, and checklists must be updated together

Workflow

1. Read the root AGENTS.md and affected child docs.
2. Read the smallest relevant references from ../agent-docs/references/:
   • root-agents-template.md
   • rule-doc-template.md
   • inventory-doc-template.md
   • child-doc-template.md
   • linking-patterns.md
   • refactor-checklist.md
3. Decide the target shape before editing:
   • keep as one rule doc
   • split rule doc from inventory
   • merge overlapping docs
   • delete obsolete leaf doc
4. Apply edits so that:
   • the root remains the starting point
   • every active child doc remains reachable from the root
   • each rule has one authoritative home
   • stale references are removed in the same change
5. If the change alters routing, authority ownership, or document shape, hand off to agent-docs-consistency.
6. If the change alters claims that depend on repository facts, hand off to agent-docs-repo-alignment.
7. Finish with agent-docs-verification.

Refactor Rules

• Prefer the smallest change that reduces ambiguity or maintenance cost.
• Do not split only for symmetry.
• Do not split when one short document already governs one clear topic.
• Do not keep a child doc that is no longer reachable from the root.
• Do not leave topic-specific rules in the root file once a narrower child doc exists.
• Do not let inventory docs become policy docs.
• Do not add an intermediate file that only repeats links without adding scope or decision logic.
• Do not create a new child doc unless it reduces ambiguity, repetition, or maintenance cost.
• In monorepos, keep common constraints in the root file and keep project-specific rules in documents near that project instead of the general rules layer.
• Do not mix general agent-doc governance with business rules, product instructions, or end-user documentation.
• Titles and filenames should state purpose directly.
• Each opening should explain purpose, trigger, and that the document must be followed in scope.
• Use repository-relative paths in backticks when referencing repo files from AGENTS or agent-docs.