Compatibility: Designed for Claude Code only. This skill uses hooks or ${CLAUDE_SKILL_DIR} which are not available on other platforms. Run on Claude Code or adapt before using elsewhere.Compare the current repository with another repository to identify changes and insights.
Overview
The /diff skill enables comparison between the current repository and a target repository specified by URL. It identifies structural similarities, conducts detailed file-by-file analysis, and produces a comprehensive diff report with meaningful insights.
Skill Syntax
/diff <repository-url>Target repository: $ARGUMENTS
Parameters:
repository-url(required): Git repository URL to compare against (HTTPS or SSH)
Workflow
Step 1: Gather Context
- Ask the user for the diff objective using AskUserQuestion:
- "What is the purpose of this comparison?" - Provide options: - "Track changes from template/fork" - Identify modifications made after forking - "Architectural comparison" - Compare design patterns and structure - "Migration analysis" - Understand differences for migration planning - "Code review" - Review changes between similar projects - "Custom" - User provides specific objective
- Store the user's objective for the report
Step 2: Clone Target Repository
- Create a temporary directory using system temp location:
mktemp -d - Clone the target repository into the temp directory:
git clone <repository-url> <temp-dir>/target-repo - Handle clone errors gracefully:
- Authentication failures - Invalid URLs - Network issues - Repository not found
Step 3: Analyze Repository Structure
- Map directory structures for both repositories:
- Use find or directory traversal to build tree structures - Identify top-level directories and organization patterns - Note framework/language indicators (package.json, Cargo.toml, go.mod, etc.)
- Calculate structural similarity:
- Compare directory hierarchies - Identify common file patterns - Determine if repositories share a template/forking relationship
- Classification:
- Similar structure (>60% overlap): Proceed with detailed file-by-file diff - Different structure (<60% overlap): Focus on architectural comparison
Step 4: Detailed Analysis
For Similar Structures (Template/Fork Relationship)
- File-level comparison:
- Generate list of all files in both repos - Categorize files: - Modified files (exist in both, different content) - Added files (only in current repo) - Removed files (only in target repo) - Identical files (same content)
- Conduct file-by-file diff:
- Use git diff --no-index for meaningful files - Focus on source code, configuration, and documentation - Skip binary files, dependencies (node_modules, vendor, etc.) - Capture line-level changes for key files
- Group changes meaningfully:
- By feature/functionality (auth changes, UI updates, etc.) - By file type (configuration, source code, tests, docs) - By impact level (breaking, enhancement, refactor, fix)
- Extract insights:
- Identify patterns in modifications - Detect new features or capabilities - Note removed functionality - Highlight configuration differences
For Different Structures (Architectural Comparison)
- Architectural analysis:
- Identify framework and language differences - Compare project organization patterns - Note build system differences - Identify dependency management approaches
- Design pattern comparison:
- Frontend architecture (if applicable) - Backend architecture (if applicable) - State management approaches - API design patterns - Testing strategies
- Coding style analysis:
- Language/framework choices - Naming conventions - Code organization philosophy - Documentation approaches - Error handling patterns
Step 5: Generate Diff Report
Check for changelog: Look for CHANGELOG.md, CHANGELOG, or RELEASES.md in both repos. If found, scan recent entries to guide characterization of changes — they often name features and breaking changes explicitly.
Determine the output filename: .codevoyant/diffs/{YYYY-MM-DD}-{target-repo-name}.md
Write the report using references/report-template.md as the structure. Keep each section to 5 bullets or fewer. File trees should show * next to modified/added files. Only include sections that have meaningful content.
Step 6: Cleanup
- Remove the temporary directory:
rm -rf <temp-dir> - Confirm successful cleanup
- Report:
✓ Diff saved to.codevoyant/diffs/{filename}
Error Handling
- Clone failures:
- Display clear error message - Suggest authentication setup if needed - Verify repository URL format
- Permission issues:
- Check write access to temp directory - Verify.claude/ directory exists and is writable
- Large repositories:
- Warn if repository is very large (>1GB) - Ask user to confirm before proceeding - Consider shallow clone: git clone --depth=1
- Binary file handling:
- Skip binary files in detailed diff - List binary files separately in report
- Memory/performance:
- Use streaming for large diffs - Limit diff context for very large files - Sample files if repository has thousands of files