Config Refactor

Name: Config Refactor
Author: fearovex

fearovex/claude-config

19 installs
1 repo stars
Updated July 19, 2026
fearovex/claude-config

Apply audited fixes to CLAUDE.md, skills, hooks, and output-styles without inventing new config rules.

About

config-refactor is a procedural agent skill for solo builders maintaining Claude Code repositories who already ran config-audit and need deterministic remediation. It reads docs/config-guidelines.md and audit-report.md as the sole specification, detects whether you are in the global claude-config repo or a downstream project, and applies fixes only to allowed targets—project mode never mutates the global layer. Stale audits trigger an explicit warning so you do not ship refactors against outdated findings. The skill fits the Ship review lane because it closes the loop on configuration hygiene before agents rely on hooks, skills, and output styles daily. Invoke it after audit-report.md exists and you are ready to edit CLAUDE.md, skills/, hooks/, or output-styles/ in a governed way.

Step 0 execution context: global claude-config repo vs project mode with read-only global layer
Requires audit-report.md and docs/config-guidelines.md; stops if inputs missing
Warns when audit is stale (>24h or older than last config commit) and waits for user confirmation
Never edits ~/.claude/ from project mode—project files only
Pairs with /config-audit; triggers include /config-refactor and apply config fixes

Config Refactor by the numbers

19 all-time installs (skills.sh)
Ranked #10,571 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
Data as of Jul 24, 2026 (Skillselion catalog sync)

npx skills add https://github.com/fearovex/claude-config --skill config-refactor

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/fearovex/claude-config/config-refactor.svg)](https://skillselion.com/skills/fearovex/claude-config/config-refactor)

Installs	19
repo stars	★ 1
Last updated	July 19, 2026
Repository	fearovex/claude-config ↗

What it does

Apply audited fixes to CLAUDE.md, skills, hooks, and output-styles without inventing new config rules.

Files

SKILL.mdMarkdownGitHub ↗

config-refactor

Applies fixes from audit-report.md against the repo configuration. Reads

docs/config-guidelines.md and audit-report.md as its spec; never invents rules.

Triggers: /config-refactor, apply config fixes, refactor claude config, fix config issues

---

Process

Step 0 — Detect execution context

Apply the same detection logic as config-audit Step 0 (per Principle 13):

Global mode — CWD is the claude-config repo. Fixes apply to repo files only.
Project mode — CWD is another project with a CLAUDE.md. Fixes apply to the

project's own files only. The global layer is read-only — config-refactor MUST NEVER edit ~/.claude/ or the source repo from project mode.

No-config mode — no CLAUDE.md in CWD. Stop and print:

No CLAUDE.md found. Nothing to refactor.

Record the mode and proceed.

Step 1 — Verify inputs

Required files in the repo root:

docs/config-guidelines.md
audit-report.md

If either is missing → stop. Tell the user to run /config-audit first.

If audit-report.md is older than 24h or older than the last commit touching CLAUDE.md, output-styles/, skills/, or hooks/ → WARNING to the user and ask whether to proceed or re-run /config-audit. STOP and wait for the answer.

Step 2 — Load and group findings

Parse audit-report.md. Group findings by the file they target. Within each file group, sort by severity (CRITICAL first) then by line number descending (so edits do not shift later line numbers).

Step 3 — Present the plan

Show the user a plan grouped by file, in this format:

File: <path>
  [CRIT-3] <title>           → <action verb> (e.g. "delete lines 145–308", "rename heading", "move to agents/")
  [WARN-7] <title>           → <action verb>
  ...
File: <path>
  ...

End the plan with a one-line summary:

Applying <N> fixes across <M> files. CRITICAL: a, WARNING: b, SUGGESTION: c.
Confirm to proceed? (y / n / pick)

y → apply everything. n → abort, leave repo untouched. pick → user selects specific finding IDs to apply (e.g. "CRIT-1, WARN-3, WARN-5").

STOP and wait for the user's choice.

Step 4 — Apply fixes

For each confirmed finding, derive the edit from the fix_hint plus the principle cited. Standard fix actions and how to execute them:

Fix hint pattern	Action
"Move scoped section to `agents/`"	Cut the section from `CLAUDE.md`; create `agents/<name>.md` with that content plus a YAML header `--- name: <name> ---`; replace the cut location in `CLAUDE.md` with a one-line reference: "Orchestrator rules live in `agents/<name>.md` — loaded on demand."
"Remove manual skill catalog"	Delete the catalog table. Add no replacement.
"OS-specific tooling assumed without declaration"	Either prefix the line with the OS marker the user confirms, or delete the line. ASK before choosing.
"Engram protocol duplicated…"	Delete the protocol block from `CLAUDE.md`. Replace with a one-line reference: "Engram protocol is injected by the `SessionStart` hook. Repo-specific topic-key conventions follow." Keep only the topic-key list.
"Rule duplicated (Principle 3.2)" between `CLAUDE.md` and an output-style	Delete the duplicate from the output-style. The output-style may add a single line: "Behavior rules from `CLAUDE.md` still apply."
"Force-read table exceeds 4 entries"	Show the user the current entries and ask which 2–4 to keep. STOP and wait.
"Rename to 'Skills — Force-read inline'"	Rename the heading. No other changes.
"Force-read entry points to missing file"	Delete the row.
Skill format violations	Add the missing frontmatter field or section. If `format` value is missing, default to `procedural` and emit a follow-up SUGGESTION to confirm.
File over hard token limit	Identify which section is the largest expendable block (orchestrator content, duplicated engram protocol, decorative philosophy). Propose the cut to the user. STOP and wait for approval.
"Dead reference" / "Reference to missing skill"	Remove the reference or update it to a valid path. If user intent is unclear, ASK.
"Project CLAUDE.md restates global rule…" (Principle 13)	Delete the duplicated line from the project `CLAUDE.md`. Add no replacement — the global rule already applies.
"Project CLAUDE.md contradicts global without override" (Principle 13)	STOP and ask the user: (a) accept the global rule and delete the project line, or (b) declare an explicit `## Overrides global` block with the reason. Never auto-resolve.
"Orphan in ~/.claude/" (Principle 12)	STOP and ask the user before deleting anything in `~/.claude/`. Never auto-delete runtime-adjacent files.

For ambiguous fixes (anything not in the table above), STOP and ask the user before editing.

Step 5 — Verify

After all edits:

1. Re-read each modified file briefly to confirm syntactic integrity (YAML frontmatter still parses, markdown headings still balanced, no orphaned bullet lists). 2. Run a lightweight self-check: for every finding marked as applied, confirm the change actually landed in the file. 3. If any verification fails → revert that specific edit and report it as UNAPPLIED in the final summary. Do NOT roll back the entire run.

Step 6 — Report and remind

Print a final summary to the user:

Applied: <N> fixes
  - <ID> <title> → <file>
Unapplied: <K> fixes (manual review required)
  - <ID> <reason>
Skipped (user chose not to apply): <S>

Next steps:
  1. Review the diff: git diff
  2. Run install.sh to deploy: bash install.sh
  3. Commit when satisfied

Do NOT run install.sh automatically. Do NOT commit. Both decisions belong to the user.

If any CRITICAL finding is still unapplied, end the summary with a one-line nudge: "⚠ <N> CRITICAL finding(s) remain — re-run /config-audit after manual review."

Step 7 — Save context to engram

Save a mem_save entry with:

title: Applied config refactor — <date>
type: config
topic_key: config/refactor-history
content: structured What/Why/Where/Learned summarizing the run.

This is mandatory so future sessions can trace the configuration evolution.

---

Rules

Never write to ~/.claude/ directly. Only edit repo files. Remind the user to run

install.sh after.

Never invent fixes. Every edit must trace back to a finding ID and a principle.
Never apply fixes the user did not confirm.
Never commit. Never run install.sh. Those are user decisions.
Never produce a unified mega-rewrite. Apply fixes file by file, finding by finding, so the

user can pin the source of every change.

If audit-report.md is missing or stale, stop and require re-audit.
If a fix requires user input (which entries to keep, which OS to declare), STOP and ask —

never default silently.