rename-with-dates

name	rename-with-dates
description	Rename documents and files (PDFs, images, screenshots, etc.) by reading their content to extract the effective/publication date, then renaming them with a "YYYY-MM-DD - Clear descriptive title.ext" format. Use when the user wants to organize files with date prefixes based on document content.
compatibility	Designed for Claude Code. Recommended model: Opus.
argument-hint	[directory or files]

Rename Documents with Date Prefixes

Rename files in a folder by extracting the effective date from their content and giving them a clean, human-readable title.

Target format

YYYY-MM-DD - Clear descriptive title.ext

Title casing: capitalize only the first word and proper nouns (title case), like a sentence.

Examples:

• 2023-11-01 - General terms and conditions.pdf
• 2025-08-01 - Credit card fees and charges.pdf
• 2025-12-01 - Key facts statement - Term deposits.pdf
• 2024-06-15 - Rewards program earning structure.png
• 2024-03-01 - Schedule of charges.pdf

Period documents that cover a date range (statement exports, period reports) may extend the prefix to YYYY-MM-DD--YYYY-MM-DD - Title.ext — preserve that convention where a folder already uses it.

Supported file types

• PDFs: Read the first few pages (and last page if needed) to find dates and understand content. The Read tool rejects PDFs over 20MB: render their pages to images with pdftoppm -png -r 30 and view those instead
• Images / Screenshots (PNG, JPG, etc.): View the image to understand its content, then summarize it into a clear descriptive title. For screenshots, the date is often embedded in the filename (e.g., Screenshot 2026-01-12 at 11.07.33.png → date is 2026-01-12)
• Office documents: for .xlsx, read docProps/core.xml inside the zip (unzip -p file.xlsx docProps/core.xml) for dcterms:created; for Apple .numbers, the package often embeds a readable preview.jpg or preview.pdf. A stray .~lock.*# file next to a document is a LibreOffice lock: the document may be open somewhere (possibly on another synced machine); stale locks are trash candidates
• Emails exported/printed to PDF: use the email's sent date from its header, never the print/export date; derive the title from the subject and outcome of the thread
• Photo archives: a folder full of personal photos (IMG_1234.jpeg dumps) is an archive, not a document set — propose skipping it wholesale instead of dating each file. Rename a photo only when it acts as a document (appliance rating plate, meter photo, signed-form snapshot), dating it from EXIF DateTimeOriginal via exiftool
• Other documents: Read content where possible to extract dates and meaning

Workflow

1. List files in the target directory (default: current working directory, or $ARGUMENTS if provided)

2. Skip files that already follow the YYYY-MM-DD - Title.ext pattern (but offer to clean up their titles if needed). A bare date with no title (like 2023-08-17.pdf) is not compliant — read the file and add the missing title (often just Invoice or Receipt inside a provider folder, where the folder name already gives context)

3. Read each file to find the effective date and understand the content:

   • For PDFs:
     • Look for explicit "Effective from..." or "Effective date" statements — prefer these
     • Look for version dates in footers (e.g., "08/2025", "v. August 14, 2023")
     • Beware date-lookalike version codes: a code like V160701.1 reads as YYMMDD but may be template artwork — if the same code appears on documents with different effective dates, it is not a date. Reference codes (like CRN FRM021121) often embed a MMDDYY date and corroborate other evidence at month precision
     • Filenames that are bare reference codes or portal export IDs (like LICDSO202600109568.pdf or bill-3733181.pdf) are almost always invoices or receipts — open them; the code itself rarely matters to the user
     • When two files resolve to the same date and the same title, re-inspect before renaming: one is usually a different document type (like an annual statement of accounts issued the same day as the monthly invoice)
     • Look for dated headers, cover pages, or document stamps
     • Use the effective/applicability date, not the publication or copyright date
   • For images/screenshots:
     • View the image to understand what it shows
     • Extract date from the original filename if it contains one (e.g., Screenshot 2026-01-12 at ...)
     • If the image contains visible dates in its content, prefer those
     • If no date can be found, ask the user
   • Match the date precision to what the document provides: use YYYY-MM-DD for exact dates, YYYY-MM for month-only, YYYY for year-only

4. Choose a clear title:

   • Use sentence case: capitalize only the first word and proper nouns

Multi-language PDF stripping

Many legal/banking documents repeat the same content translated across several languages, organized as consecutive blocks of pages (e.g., pages 1-10 in English, 11-20 in Arabic, 21-30 in Bulgarian). When detected, propose stripping to keep only English and French pages.

Detection

1. While reading a PDF, sample pages throughout the document (not just the beginning) to detect language blocks
2. A document qualifies for stripping only if:
   • The content is repeated in blocks of pages, each block being a full translation of the same content
   • Each page is in a single language — if a page mixes multiple languages (e.g., English and Arabic side by side, or bilingual tables), do NOT propose stripping that document
   • The granularity is the page: each page belongs to exactly one language
3. Identify the page ranges for each language block (e.g., "Pages 1-25: English, Pages 26-50: Arabic, Pages 51-75: French")

Proposal

• Present findings clearly: list each language detected and its page range
• Propose which pages to keep (English and French) and which to remove
• Ask the user for confirmation before modifying the PDF
• Use qpdf to extract only the desired pages into a new file (qpdf in.pdf --pages . 1-4 -- out.pdf)
• Verify before replacing: the original's qpdf --show-npages must match the detected page total, and the stripped output must match the kept range length — skip the file on any mismatch
• Replace the original file with the stripped version, and stash the pre-strip originals in the Trash batch folder (like ~/.Trash/{folder} cleanup YYYY-MM-DD/pre-strip originals/) as a safety net
• For more than a handful of files, drive the loop with a small Python script (manifest of filename + keep range + expected total) instead of ad-hoc shell commands

When NOT to strip

• The document is signed: signed forms and agreements are legal records — never alter them, even when their languages are cleanly block-structured
• Pages contain multiple languages (bilingual layouts, side-by-side translations)
• The translations are not full-document blocks (e.g., just a translated summary at the end)
• The document has only one language
• You are not confident about the language boundaries

Required tools

This skill depends on third-party CLI tools. At the start of execution, check if each is available and propose to install any that are missing via brew install.

Tool	Brew package	Used for
qpdf	qpdf	Extracting page ranges from PDFs (multi-language stripping), page counts (--show-npages)
pdftoppm	poppler	Rendering PDF pages — the Read tool depends on it to view PDFs at all
pdftotext	poppler	Extracting text per page for language detection in large PDFs
exiftool	exiftool	Reading PDF metadata (CreationDate, ModDate) as date fallback

mdls (macOS built-in) can also be used for metadata and does not need installation.

If a missing tool is needed for the current run, propose the install command and ask the user before proceeding. If the tool is not needed (e.g., no multi-language PDFs detected, so qpdf is not required), skip silently.

If the target folder contains any PDFs, install poppler first thing: without pdftoppm the Read tool cannot render PDF pages, so no PDF can be inspected at all. Note that brew install writes to /opt/homebrew and usually needs to run outside the command sandbox.

Important rules

• Always extract dates from file content (or filename for screenshots), never from file system metadata
• For PDFs, read the first few pages (and last page if needed) to find the date
• For images, always view the image to produce a meaningful title — never just use the original filename
• If a document has both a publication date and an "Effective from" date, use the effective date
• If no date can be found in the content or filename, fall back to PDF metadata (CreationDate, ModDate) using mdls or exiftool. Only use file system dates (modification date) as a last resort
• If no date can be found at all, flag it to the user and ask what to do
• Use mv for renaming — never copy-and-delete
• Folders can change while you work (the user may be acting in parallel, or cloud sync may intervene): re-check that files still exist before acting on them, and if files vanish mid-run, surface it to the user — never restore things from the Trash on your own initiative. Folders may also be renamed mid-run: if a move fails, re-resolve the path before assuming the file is gone
• Reading several look-alike files in one parallel batch (same provider, same visit date, same document family) risks cross-attributing the returned pages to the wrong filename — one run swapped a prescription and a tomography report scanned the same day, and only the user caught it. Read ambiguous siblings one at a time, and after renaming a batch of same-day scans, re-render a page of each renamed file to confirm its content matches the new title
• For large trees, fan out read-only subagents to extract dates and propose titles per folder, but review their proposals and execute all renames yourself so titles stay consistent across folders