move-a-file_skill

Overview

This skill performs safe file moves or renames in a codebase while automatically finding and updating all references in source code, documentation, and configuration files. It validates paths, updates references with context-aware path calculations, performs a git-preserving move, and reports a clear summary of changes and any items needing manual review.

How this skill works

The agent first validates the old and new paths and ensures the new parent directory can be created without overwriting existing files. It then searches the repository for references using multiple patterns (filename, full relative path, path variants and import forms) across source, docs, config, and build files. The agent updates each reference with the correct form for its context, runs git mv to move the file, verifies the result, and produces a summary listing moved path, updated files, and outstanding uncertainties.

When to use it

• Rename a single source file while preserving history
• Move a documentation file and update links across docs and README
• Refactor a module so imports and build configs stay correct
• Relocate a single file referenced in multiple languages or config formats
• Update file placement during reorganization without breaking CI/builds

Best practices

• Always validate that old path exists and new path won’t overwrite existing files
• Search with multiple patterns: exact name, full relative path, leading ./, and import variations
• Update references using the language or file-type conventions (imports vs. root-relative links)
• Use git mv (and mkdir -p for the new parent) to preserve history
• Report any ambiguous references for manual review; don’t guess in uncertain cases

Example use cases

• Rename a Python module and update from/import statements across the codebase
• Move a Markdown doc into a nested docs folder and update README links
• Relocate a shell script used by CI and update all source commands and Makefile entries
• Change the path of a config file and update YAML/JSON references used by services