name	agent-config-migrate
version	1
description	Audits your CLAUDE.md and Claude Code configuration, then generates a migration plan to the skills+hooks architecture. Classifies each section as invariant, workflow, or router. Outputs token savings estimate, stub skill files, and hook boilerplate. Use when CLAUDE.md exceeds 300 lines, skills aren't triggering reliably, or on "audit CLAUDE.md", "refactor my config", "slim down CLAUDE.md", "skills not triggering".
allowed-tools	Read Glob Write Bash

agent-config-migrate

Audits CLAUDE.md and generates a migration plan to the skills+hooks architecture.

Phase 1: Discovery

Find and read CLAUDE.md in the current project root.
- If CLAUDE.md has @import directives, read all imported files too.
- If no CLAUDE.md exists: report "No CLAUDE.md found" and offer to generate a starter template. Stop here.
Run: wc -l CLAUDE.md (and each imported file) — record total line count.
Glob for .claude/skills//*.md and skills//*.md — list any already-extracted skills. Note their names.
Run: ls -la .claude/ — note what directories and files already exist.

Phase 2: Classification

Read the classification heuristics in references/classification-guide.md.

For each section in CLAUDE.md, assign a type:

invariant: universal constraint applying to every Claude interaction. Keep in CLAUDE.md.
workflow: a named, multi-step procedure for a specific task type. Extract as a skill stub.
router: conditional/trigger logic deciding what action to take. Extract as a UserPromptSubmit hook.

List each section with its assigned type and a one-line reason.

Phase 3: Report (always output this)

Print the structured audit report using the template in references/templates.md § Report Template.

Include:

Total lines, lines to keep, lines to extract
Estimated token savings percentage (lines extracted / total lines × 100)
Section-by-section classification table
For each workflow section: proposed skill slug and one-line description
Hook recommendation: whether a UserPromptSubmit hook is needed and what it should evaluate

If running in audit-only mode (no --apply flag): stop here. Print: "Review the plan above. Re-run with /agent-config-migrate --apply to generate the output files."

Phase 4: Generation (only with --apply)

Before writing any files: print the full list of files that will be created or modified. Ask for confirmation.

On confirmation:

Write .claude/skills/{slug}/SKILL.md for each extracted workflow, using the skill stub template in references/templates.md.
Merge the hook configuration from references/templates.md into .claude/settings.json under the hooks.UserPromptSubmit key. If settings.json does not exist, create it. If a UserPromptSubmit hook already exists, append to its hooks array rather than overwriting. Populate {SKILL_LIST} with the actual skill names from step 1.
Rewrite CLAUDE.md: keep invariant sections verbatim, replace each extracted section with a one-line @reference comment, add an "Available Skills" section listing all skill slugs.
Create CLAUDE.md.bak (copy of original) before rewriting.
Output a summary: files created, lines before/after, token savings. End the summary with: "Restart Claude Code to pick up the rewritten CLAUDE.md — your current session still has the old context loaded."

Quality rules

Never write the slimmed CLAUDE.md without first creating CLAUDE.md.bak.
The invariant sections must be reproduced verbatim in the new CLAUDE.md — do not rephrase or summarize them.
Each skill stub must include the extracted instructions exactly as written, not summarized — the user will refine them.
The UserPromptSubmit hook prompt must include all skill slugs by name.
If token savings estimate is below 20%, note this in the report: "Your CLAUDE.md is already relatively lean. Migration may not be worth the overhead."

agent-config-migrate

Audits CLAUDE.md and generates a migration plan to the skills+hooks architecture.

Phase 1: Discovery

Find and read CLAUDE.md in the current project root.

If CLAUDE.md has @import directives, read all imported files too.
If no CLAUDE.md exists: report "No CLAUDE.md found" and offer to generate a starter template. Stop here.

Run: wc -l CLAUDE.md (and each imported file) — record total line count.

Glob for .claude/skills//*.md and skills//*.md — list any already-extracted skills. Note their names.

Run: ls -la .claude/ — note what directories and files already exist.

Phase 2: Classification

For each section in CLAUDE.md, assign a type:

invariant: universal constraint applying to every Claude interaction. Keep in CLAUDE.md.

workflow: a named, multi-step procedure for a specific task type. Extract as a skill stub.

router: conditional/trigger logic deciding what action to take. Extract as a UserPromptSubmit hook.

List each section with its assigned type and a one-line reason.

Phase 3: Report (always output this)

Print the structured audit report using the template in references/templates.md § Report Template.

Include:

Total lines, lines to keep, lines to extract

Estimated token savings percentage (lines extracted / total lines × 100)

Section-by-section classification table

For each workflow section: proposed skill slug and one-line description

Hook recommendation: whether a UserPromptSubmit hook is needed and what it should evaluate

If running in audit-only mode (no --apply flag): stop here. Print: "Review the plan above. Re-run with /agent-config-migrate --apply to generate the output files."

Phase 4: Generation (only with --apply)

Before writing any files: print the full list of files that will be created or modified. Ask for confirmation.

On confirmation:

Write .claude/skills/{slug}/SKILL.md for each extracted workflow, using the skill stub template in references/templates.md.

Merge the hook configuration from references/templates.md into .claude/settings.json under the hooks.UserPromptSubmit key. If settings.json does not exist, create it. If a UserPromptSubmit hook already exists, append to its hooks array rather than overwriting. Populate {SKILL_LIST} with the actual skill names from step 1.

Rewrite CLAUDE.md: keep invariant sections verbatim, replace each extracted section with a one-line @reference comment, add an "Available Skills" section listing all skill slugs.

Create CLAUDE.md.bak (copy of original) before rewriting.

Output a summary: files created, lines before/after, token savings. End the summary with: "Restart Claude Code to pick up the rewritten CLAUDE.md — your current session still has the old context loaded."

Quality rules

Never write the slimmed CLAUDE.md without first creating CLAUDE.md.bak.

The invariant sections must be reproduced verbatim in the new CLAUDE.md — do not rephrase or summarize them.

Each skill stub must include the extracted instructions exactly as written, not summarized — the user will refine them.

The UserPromptSubmit hook prompt must include all skill slugs by name.

If token savings estimate is below 20%, note this in the report: "Your CLAUDE.md is already relatively lean. Migration may not be worth the overhead."