Move a File

This skill instructs AI agents on how to safely move or rename files in a codebase while automatically finding and updating all references to the file in source code, documentation, and configuration files.

Inputs

The move-a-file skill takes the following inputs:

• Old file path: The current path of the file to move/rename (relative to project root)
• New file path: The destination path for the file (relative to project root)
• Context: Any additional context about what the file contains or why it's being moved

Workflow for AI Agents

When this skill is invoked, the AI agent MUST follow these steps in order:

1. Validate File Paths

Before proceeding, verify that:

• The old file path exists
• The new file path's parent directory exists (or can be created)
• The new file path does not already exist (to avoid overwrites)
• Both paths are relative to the project root

If any validation fails, inform the user and abort.

2. Search for All References

Use rg (ripgrep) or grep to find all references to the file across the codebase.

IMPORTANT: Search for multiple patterns to catch all references:

1. Exact filename: Search for the exact filename (without path)

   rg --type-add 'docs:*.md' --type-add 'config:*.{yaml,yml,json,toml}' \
      -t md -t config -t py -t js -t sh -t c -t cpp \
      "<filename>"
   

2. Full relative path: Search for the full path from project root

   rg --type-add 'docs:*.md' --type-add 'config:*.{yaml,yml,json,toml}' \
      -t md -t config -t py -t js -t sh -t c -t cpp \
      "<old-path>"
   

3. Path variations: Search for common path variations

   • With leading ./: "./<old-path>"
   • Without extension (if applicable): "<path-without-ext>"
   • In import statements: "import.*<filename-without-ext>"

Search scope: Include at minimum:

• Source code files (.py, .js, .sh, .c, .cpp, etc.)
• Documentation files (.md, .txt, .rst)
• Configuration files (.yaml, .yml, .json, .toml)
• Build files (Makefile, CMakeLists.txt, package.json)

3. Review and Update References

For each file containing a reference:

• Read the file to understand the context
• Determine the correct new path to use (may be relative to that file's location)
• Update the reference using the Edit tool
• Report what was changed in that file

Path calculation rules:

• For documentation and config files: usually use paths relative to project root
• For import statements: follow the language's import conventions
• For file system operations: may need relative paths from the current file

4. Move the File

After updating all references, move the file:

git mv "<old-path>" "<new-path>"

If the parent directory of the new path doesn't exist:

mkdir -p "$(dirname '<new-path>')" && git mv "<old-path>" "<new-path>"

5. Verify and Report

After moving the file:

1. Verify the new file exists: ls "<new-path>"
2. Report summary to the user:
   • Old path → New path
   • Number of files updated
   • List of updated files with brief description of changes
   • Any references that might need manual review

Examples

Example 1: Renaming a Skill File

Context: User wants to rename git-commit/SKILL.md to commit-msg/SKILL.md

Workflow:

User: Use move-a-file to rename the git-commit skill to commit-msg

Agent: I'll move the file and update all references.

1. Validating paths...
   - Source exists: .claude/skills/git-commit/SKILL.md ✓
   - Destination available: .claude/skills/commit-msg/SKILL.md ✓

2. Searching for references to "git-commit"...
   Found references in:
   - .claude/skills/CLAUDE.md (2 references)
   - .claude/commands/README.md (1 reference)
   - README.md (1 reference)

3. Updating references...
   - .claude/skills/CLAUDE.md:79 - Updated skill name reference
   - .claude/skills/CLAUDE.md:123 - Updated example path
   - .claude/commands/README.md:45 - Updated skill link
   - README.md:67 - Updated workflow reference

4. Moving the file...
   [Runs: mkdir -p .claude/skills/commit-msg && git mv .claude/skills/git-commit/SKILL.md .claude/skills/commit-msg/SKILL.md]

5. Summary:
   Moved: .claude/skills/git-commit/SKILL.md → .claude/skills/commit-msg/SKILL.md
   Updated 4 references across 3 files

Example 2: Moving Documentation File

Context: User wants to reorganize docs by moving a file

Workflow:

User: Move docs/workflow.md to docs/agent/workflow.md

Agent: I'll move the file and update all references.

1. Validating paths...
   - Source exists: docs/workflow.md ✓
   - Creating parent directory: docs/agent/ ✓

2. Searching for references...
   Found references in:
   - README.md (3 references)
   - docs/index.md (1 reference)
   - .claude/skills/plan-guideline/SKILL.md (1 reference)

3. Updating references...
   - README.md:23 - Updated link: [workflow](docs/workflow.md) → [workflow](docs/agent/workflow.md)
   - README.md:45 - Updated link in list
   - README.md:89 - Updated reference in text
   - docs/index.md:12 - Updated link
   - .claude/skills/plan-guideline/SKILL.md:234 - Updated documentation reference

4. Moving the file...
   [Runs: mkdir -p docs/agent && git mv docs/workflow.md docs/agent/workflow.md]

5. Summary:
   Moved: docs/workflow.md → docs/agent/workflow.md
   Updated 5 references across 3 files

Example 3: No References Found

Context: Moving a new file that hasn't been referenced yet

Workflow:

User: Move temp/draft.md to docs/draft/implementation.md

Agent: I'll move the file and check for references.

1. Validating paths...
   - Source exists: temp/draft.md ✓
   - Creating parent directory: docs/draft/ ✓

2. Searching for references...
   No references found to "draft.md" or "temp/draft.md"

3. Moving the file...
   [Runs: mkdir -p docs/draft && git mv temp/draft.md docs/draft/implementation.md]

4. Summary:
   Moved: temp/draft.md → docs/draft/implementation.md
   No references needed updating

Important Notes

1. Always use git mv: This preserves file history in git. Never use regular mv command.

2. Case sensitivity: File systems may be case-insensitive, but git is case-sensitive. Be careful when changing only the case of a filename.

3. Search thoroughly: Different files may reference the moved file in different ways. Use multiple search patterns to catch all variations.

4. Path relativity: When updating references, consider whether the reference should be:

   • Relative to project root
   • Relative to the file containing the reference
   • An absolute path

5. Import statements: Programming language imports may need special handling:

   • Python: from module.submodule import file
   • JavaScript: import { func } from './path/to/file'
   • Shell: source ./path/to/file.sh

6. Glob patterns: Also search for glob patterns that might match the file:

   • docs/**/*.md might be used to reference all markdown files
   • These might need updating if the file moves to a different directory structure

7. Report uncertainty: If you find a reference that you're unsure how to update, include it in the final report and ask the user to review it manually.

8. Don't move directories: This skill is for moving individual files only. For moving entire directories, the process is more complex and should be handled separately.