Skill

compare-documents

Compare two legal documents (PDF, DOCX, TXT) and generate detailed visual diffs with color-coded changes, change heatmaps, and structured change logs. Use when: (1) a user wants to compare two versions of a document, (2) a user says 'compare these documents', 'what changed between these versions', 'show me the differences', 'diff these files', or 'analyze the changes', (3) a user has an original and revised version of a contract, agreement, or policy, (4) a user needs to review edits made to a legal document, (5) a user wants a visual side-by-side comparison.

npx claudepluginhub jdrodriguez/legal-toolkit --plugin legal-toolkit

Tool Access

This skill uses the workspace's default tool permissions.

Preview

You are a document forensics specialist for legal review.

Supporting Assets

scripts/check_dependencies.pyscripts/compare_documents.py

SKILL.md

Similar Skills

contract-compare

1.9k

Compares two contract versions side-by-side to detect added, removed, modified clauses with favorability analysis. Useful for revised contracts, redlines, and negotiations.

3 tools

general-legal-assistant

compare-docs

Semantically compares two documents with relationship preservation to identify content and structural differences. Useful for verifying spec equivalence, doc rewrites, or change impacts via /compare-docs.

cat

adeu-redlining

Reviews and redlines existing DOCX files with Track Changes. Extracts to Markdown, diffs docs, proposes/applies edits as ins/del XML, accepts/rejects changes, replies to comments.

1 file

adeu-redlining

Stats

Parent Repo Stars2

Parent Repo Forks0

Last CommitMar 11, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

Legal Document Comparison Suite

You are a document forensics specialist for legal review.

Compare two documents and generate comprehensive visual diffs with change analysis.

Supported formats: .pdf, .docx, .txt Input: two document paths (file1 = original, file2 = revised)

Skill Directory

Scripts are in the scripts/ subdirectory of this skill's directory. Resolve SKILL_DIR as the absolute path of this SKILL.md file's parent directory. Use SKILL_DIR in all script paths below.

Process

Step 1: Validate Input

Confirm the user provided two document paths. If not, ask: "Please provide the paths to the two documents you want to compare. The first should be the original, and the second the revised version."
Verify both files exist and have supported extensions (.pdf, .docx, .txt).
The two files do not need to be the same format -- you can compare a PDF against a DOCX.
Optionally ask for labels (e.g., "Original" and "Revised", or "Draft v1" and "Draft v2").

Step 2: Check Dependencies

python3 "$SKILL_DIR/scripts/check_dependencies.py"

Exit 0: all good. Exit 1: packages were installed (proceed). Exit 2: failed (report to user).

Step 3: Run Comparison

Determine the output directory based on file1's location:

OUTPUT_DIR="{file1_parent_dir}/{file1_name_without_ext}_comparison"

mkdir -p "$OUTPUT_DIR"

python3 "$SKILL_DIR/scripts/compare_documents.py" \
  --file1 "<path_to_original>" \
  --file2 "<path_to_revised>" \
  --output-dir "$OUTPUT_DIR" \
  --labels "Original,Revised"

The script prints JSON to stdout with the comparison results. Progress messages go to stderr.

Step 4: Present Summary

Read the script's JSON output. Present to the user:

Overview: "Compared {file1} against {file2}"
Change statistics:
- Total changes: X additions, Y deletions, Z modifications
- Percentage of document changed
- Most-changed sections
Key changes: List the 5 most significant modifications (largest text changes)
Warnings: Flag any sections that were completely removed or added

Read $OUTPUT_DIR/comparison_summary.txt and present a condensed version.

Step 5: Direct User to Visual Review

Tell the user:

"I've generated a visual comparison. Open $OUTPUT_DIR/comparison.html in your browser to see the side-by-side diff with color coding:

Green: Added text

Red: Deleted text

Yellow: Modified text

I also generated a change heatmap at $OUTPUT_DIR/change_heatmap.html showing which sections had the most changes."

Step 6: Offer Next Steps

Present these options:

Generate a formal change summary (.docx): Use the docx skill to create a Word document listing all changes with context.
Focus on specific sections: "Would you like me to analyze changes in a particular section in more detail?"
Generate redline: "For a tracked-changes version, use /legal-toolkit:track-changes with the same two files."
Export change log: "The structured change log is at $OUTPUT_DIR/change_log.json if you need it for further processing."

Accuracy and QA (Required)

Anti-hallucination rules (include in ALL subagent prompts):

Every factual claim must cite a source document — unsourced claims are prohibited
Never fabricate legal citations — all case law → [VERIFY], unknown authority → [CASE LAW RESEARCH NEEDED]
Never assume facts not in source material — missing info → [NEEDS INVESTIGATION]
Quote exactly when comparing documents — label analysis vs. facts distinctly

QA review: After completing all work but BEFORE presenting to the user, invoke /legal-toolkit:qa-check on the work/output directory. Do not skip this step.

Error Handling

Path not found: Ask user to verify the paths
Unsupported format: Supported types are .pdf, .docx, .txt
Identical documents: Report that no differences were found
Empty extraction: File may be scanned/image-only. Delegate OCR to a subagent: launch an Agent (subagent_type: "general-purpose") with prompt: "Run /legal-toolkit:extract-text on {file_path} and write the extracted text to {parent_dir}/{filename}_ocr.txt." Re-run comparison on the OCR output.
Script not found: Verify the skill is installed (ls $SKILL_DIR/scripts/)