agent-instruction-consolidator

name	agent-instruction-consolidator
description	MANUAL-ONLY; never auto-invoke. Audit and align agent instruction files across tools — CLAUDE.md (root, nested, local), AGENTS.md, Cursor rules, GitHub Copilot instructions, Windsurf and Cline rules, and similar — into one consistent source of truth. Invoke explicitly when instruction files conflict, duplicate each other, or have drifted, or after adopting a new AI tool. Produces an inventory, a conflict and duplication matrix, and a consolidation proposal with a rule-preservation diff; edits files only after the proposal is approved. Manual-only, because instruction files steer every future agent run.
disable-model-invocation	true

Agent Instruction Consolidator

Purpose

Make every AI tool in the repo read the same truth. This skill inventories all agent-instruction files, extracts and compares their rules, exposes conflicts and drift, and consolidates to a designated canonical source with thin per-tool pointers — proving with a before/after rule inventory that no rule was silently lost or changed along the way.

Use When

• Use when (explicitly invoked by a human): instruction files disagree (different test commands, contradictory style rules), duplicated content has drifted apart, a new AI tool was adopted, or an audit of agent guidance is requested.
• Do NOT use when: authoring a first instruction file for a repo that has none — there is nothing to consolidate.
• Do NOT use when: resolving conflicts between docs and code — that is source-of-truth-reconciler; this skill is specifically about agent-instruction files.
• Never auto-invoked: consolidation edits files that steer every future agent run — supply-chain-sensitive, human-initiated only (disable-model-invocation: true).

Inputs to Inspect

1. Every instruction file present — locate them with references/instruction-file-map.md: CLAUDE.md (root and nested), CLAUDE.local.md, AGENTS.md, .cursorrules and .cursor/rules/, .github/copilot-instructions.md and .github/instructions/, .windsurfrules, .clinerules, plus repo-custom standards docs that function as agent instructions.
2. Which tools are actually in use (configs, CI, teammate signals).
3. Each tool's precedence semantics (nested overrides root? local overrides repo? per the map).
4. Git history of the instruction files — who drifted from whom, and when.

Workflow

1. Inventory: find every instruction file; record path, the tool(s) that read it, its scope (repo / directory / user), and its precedence semantics.
2. Extract rules: normalize each file into discrete rules (build/test commands, style, security, workflow, tone).
3. Build the matrix: rule × file. Classify every rule: unique | duplicate (identical) | drifted (same topic, different content) | conflicting (incompatible) | stale (references removed tooling or paths).
4. Propose consolidation: designate ONE canonical source; per-tool files become thin pointers or minimal tool-specific supplements; nested or dir-scoped overrides are preserved intentionally and documented. Include migration steps and a before/after rule inventory giving every rule a disposition: kept | merged | superseded-by | dropped-with-reason.
5. STOP for approval. Present the matrix and proposal. No file edits before explicit approval.
6. Apply (after approval): make exactly the approved edits, nothing more.
7. Verify: re-run the inventory; the post-state matrix must show zero conflicts and no undisposed rules.

Output Format

INSTRUCTION CONSOLIDATION REPORT
Inventory: <file → tool(s), scope, precedence>
Matrix:    <rule × file, with classification>
Conflicts: <each, with the divergent texts quoted>
Proposal:  canonical = <file>; <per-file plan>
Rule preservation: <every rule → kept | merged | superseded | dropped (reason)>
Status: AWAITING APPROVAL | APPLIED (verified)

Validation Checklist

• Every known instruction-file location checked, not just the famous ones.
• Every rule in the matrix has a disposition; none vanish without a stated reason.
• Tool precedence semantics respected — a nested override is intent, not drift, unless shown otherwise.
• No edits made before explicit approval.
• Post-apply inventory re-run and clean.

Gotchas

• Instruction files are executable-adjacent: a bad merge here silently changes every future agent run in the repo. That is why this skill is manual-only and proposal-first.
• Nested CLAUDE.md files are often deliberate directory-scoped overrides — consolidating them "up" can destroy intended behavior.
• Tools differ on precedence and even on which files they read; verify against the map rather than assuming symmetry.
• CLAUDE.local.md and user-level files may live outside the repo and explain "phantom" behavior differences between machines.
• Two files that agree today will drift again — the end state is one canonical file plus pointers, not N synchronized copies.

Stop Conditions

• Proposal complete → full stop until explicit human approval. Applying an unapproved consolidation is this skill's defining failure.
• A conflict encodes a genuine team disagreement (both rules actively defended) → escalate; do not pick a winner.
• An instruction file contains security-relevant rules that consolidation would weaken or reorder → halt and flag before proposing.
• Rules exist for a tool that cannot be identified → ask before classifying them as stale.

Supporting Files

• references/instruction-file-map.md — file locations, owning tools, scope, and precedence semantics.
• evals/evals.json — behavior cases, including the no-edit-before-approval stop.
• Manual-only invocation prevents trigger overlap, so no trigger-evals file.