Path Hygiene Repair

Path Hygiene Repair

Purpose

Detect files belonging to the Claude AI agent system that are in the wrong location, fix their placement to the canonical path, and optionally leave a thin pointer (symlink or redirect note) at the old location. Specifically handles username path mismatches (e.g., /Users/ vs $HOME), SSD vs. local drive placement confusion, project-scoped vs. global-scoped placement errors, and accidental nesting.

When to use

• A skill, agent, or config file is not loading and the path in a config points to a non-existent location.
• ~/.claude/claude-system.toml contains paths referencing an old username or home directory.
• Files were installed on an external SSD (/Volumes/...) but the system expects them under $HOME/.
• A SKILL.md was placed at ~/.claude/SKILL.md (root level) instead of ~/.claude/skills/skill-name/SKILL.md.
• A global skill was placed inside a project directory (~/project/.claude/skills/) and should be at ~/.claude/skills/.
• After migrating a user account, paths contain the old username throughout config files.

When not to use

• The file placement is correct and the issue is malformed content — use global-installation-audit to diagnose.
• The path issue is inside source code or a project repo (not the ~/.claude/ installation) — fix it directly in the project.
• The goal is to move large directories across volumes — this skill handles ~/.claude/ files, not bulk data migrations.
• The path error is in a third-party tool's config that is outside the Claude system.

Procedure

Phase 1: Identify the canonical path map

The canonical installation for user -m1 on macOS:

Home: $HOME/
Claude: $HOME/.claude/
Skills: $HOME/.claude/skills/<skill-name>/SKILL.md
Agents: $HOME/.claude/agents/<agent-name>/AGENT.md
Config: $HOME/.claude/claude-system.toml
System: $HOME/.claude/CLAUDE.md
Tools: $HOME/.claude/tools/
Backups: $HOME/.claude/backups/

Non-canonical paths to detect:

• /Users// (missing -m1 suffix)
• /Volumes/*$HOME/ (SSD path, not local)
• ~/Documents/.claude/ or any non-home location
• .claude/ at project root intended as global

Phase 2: Detect misplaced files

# 1. Find any .claude directories not under ~/.claude
find $HOME -name ".claude" -type d \
 ! -path "$HOME/.claude" \
 ! -path "*/node_modules/*" 2>/dev/null

# 2. Find SKILL.md files not under ~/.claude/skills/
find $HOME -name "SKILL.md" \
 ! -path "$HOME/.claude/skills/*" 2>/dev/null

# 3. Find AGENT.md files not under ~/.claude/agents/
find $HOME -name "AGENT.md" \
 ! -path "$HOME/.claude/agents/*" 2>/dev/null

# 4. Check for SSD-based files
find /Volumes -name "SKILL.md" -o -name "AGENT.md" -o -name "CLAUDE.md" \
 2>/dev/null | head -20

# 5. Check for old username in config files
grep -rn "[^-]" ~/.claude/ 2>/dev/null | grep -v ".bak"
grep -rn "/Volumes/" ~/.claude/ 2>/dev/null

Phase 3: Verify canonical destination is writable

ls -la $HOME/.claude/
touch $HOME/.claude/.write-test && \
 rm $HOME/.claude/.write-test && \
 echo "Writable" || echo "NOT WRITABLE"

Phase 4: Backup before repair

BACKUP_TS=$(date +%Y%m%d-%H%M%S)
BACKUP_DIR="$HOME/.claude/backups/pre-repair-$BACKUP_TS"
mkdir -p "$BACKUP_DIR"
# Only back up files being moved, not the entire ~/.claude
cp -r [affected-file-or-dir] "$BACKUP_DIR/"
echo "Backed up to $BACKUP_DIR"

Phase 5: Execute repairs (one at a time, with confirmation)

Pattern A — Move misplaced skill to canonical location:

# Create canonical slot
mkdir -p ~/.claude/skills/<skill-name>
# Move
mv /path/to/wrong/location/SKILL.md ~/.claude/skills/<skill-name>/SKILL.md
# Verify
ls -la ~/.claude/skills/<skill-name>/SKILL.md

Pattern B — Fix username in config file:

# Preview what will change
grep -n "[^-]" ~/.claude/claude-system.toml
# Apply with sed (macOS syntax)
sed -i '' 's|/Users//|$HOME/|g' ~/.claude/claude-system.toml
# Verify
grep "Users/" ~/.claude/claude-system.toml

Pattern C — Fix SSD path to local path:

# Identify SSD path prefix
VOLUME_PATH=$(ls /Volumes/ | grep -i macintosh 2>/dev/null || echo "IDENTIFY MANUALLY")
# Replace in config
sed -i '' "s|/Volumes/$VOLUME_PATH$HOME|$HOME|g" \
 ~/.claude/claude-system.toml

Pattern D — Leave a thin pointer at old location:

# Symlink (preferred — transparent to file reads)
ln -s $HOME/.claude/skills/<skill-name>/SKILL.md \
 /path/to/old/location/SKILL.md
# OR: Leave a redirect note (if symlink is not appropriate)
echo "This file has moved to: ~/.claude/skills/<skill-name>/SKILL.md" > \
 /path/to/old/location/SKILL.md.moved

Phase 6: Post-repair verification

# Re-run the audit commands from global-installation-audit Phase 1–3
ls ~/.claude/skills/ | wc -l
ls ~/.claude/agents/ | wc -l
cat ~/.claude/claude-system.toml
# Confirm no remaining stale paths
grep -rn "[^-]" ~/.claude/ 2>/dev/null | grep -v ".bak" | grep -v backups/
grep -rn "/Volumes/" ~/.claude/ 2>/dev/null | grep -v backups/

Checklist

• Canonical path map reviewed for current username (-m1)
• Misplaced files found via find (not assumed)
• SSD / volume paths checked
• Old username (``) in config files checked
• Canonical destination verified as writable
• Backup created before any file is moved or overwritten
• Each repair executed one at a time with verification
• Thin pointer (symlink or redirect note) left at old location when required
• Post-repair verification confirms canonical paths resolve correctly
• No stale paths remain in claude-system.toml or other config files

Common issues & anti-patterns

• Moving without backing up: A misidentified "misplaced" file that was actually correct in context is unrecoverable without a backup.
• Fixing the symlink instead of the source: If a symlink at the canonical path points to the SSD, fix the symlink target — do not move the file from the SSD and break the symlink.
• Username confusion between `` and -m1: These are different home directories. /Users/ may not exist or may belong to a different account. Never assume they are equivalent.
• sed on the wrong file: Running sed to replace paths without checking which files contain stale paths first.
• No pointer left at old location: Scripts or agents with hardcoded old paths will silently fail. Always leave a pointer during a transition.
• Project .claude/ confused for global ~/.claude/: A project-scoped .claude/skills/ is intentional and correct for that project. Do not move project skills to global unless the user confirms intent.
• Repair applied to all files at once: Run repairs one file at a time. A batch sed -i across all of ~/.claude/ can corrupt files that were correct.

Required output

## Path Hygiene Repair Report

Date: [date]
User home: $HOME/
Canonical Claude root: $HOME/.claude/

### Detection findings

#### Misplaced SKILL.md files
| Found path | Canonical path | Action |
|---|---|---|
| [path] | [canonical] | [move / already correct] |

#### Misplaced AGENT.md files
[same format]

#### Stale username references in config
| File | Line | Stale value | Correct value |
|---|---|---|---|
| [file] | [N] | /Users// | $HOME/ |

#### SSD / volume path references
| File | Line | Value | Action |
|---|---|---|---|

### Backup created
[backup path and contents]

### Repairs applied
1. [Action] [from-path] → [to-path] — [DONE / SKIPPED (reason)]

### Pointers left
| Old path | Points to |
|---|---|
| [old] | [canonical] |

### Post-repair verification
- Skills found at canonical path: [N]
- Agents found at canonical path: [N]
- Stale paths remaining: [none / list]

### Status
[CLEAN / ISSUES REMAIN] — [summary]

Safety

• Never delete a file during path repair — always move (preserve the original bytes).
• Do not repair paths in project repositories; confine all operations to ~/.claude/ and its subdirectories.
• If a file exists at both the old and new canonical paths, halt and report the conflict — do not overwrite silently.
• Confirm with the user before applying any sed -i to config files that affect all agents and skills.