split agent-docs skills

skills/agent-docs-refactor/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: agent-docs-refactor
+description: 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`.

skills/agent-docs-refactor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Refactor agent-docs"
+  short_description: "Edit or restructure agent-docs"
+  default_prompt: "Use $agent-docs-refactor to create, split, merge, reroute, or rewrite AGENTS.md and agent-docs, including necessary follow-up consistency, repo-alignment, and verification steps."