playbooks

home / skills / nweii / agent-stuff / rename-files

rename-files skill

/skills/dev/rename-files

This skill analyzes file content and suggests intelligent, convention-based renames for documents and creative files to improve organization.

npx playbooks add skill nweii/agent-stuff --skill rename-files

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
3.1 KB
---
name: rename-files
description: "Analyze file content and propose intelligent renames using context-aware naming conventions. Date-prefixed for transactional/periodic documents, content-first for creative works. Use for organizing files, cleaning up downloads, or standardizing filenames."
metadata:
  author: nweii
  version: "1.0.0"
---

# Rename Files

Analyze files and propose intelligent renames based on content type and metadata. Provide: a single file path, list of file paths, or folder path.

## Naming Conventions

### Transactional/Periodic Documents

**Repetitive transactions** (orders, receipts, invoices, appointments):

- Format: `YYYY-MM-DD Category Type - Details.extension`
- Example: `2025-06-13 Amazon Order 123-456 - USB Cable.pdf`
- Include: dates, entity names, order/invoice numbers, item descriptions

**Periodic documents** (statements, bills, forms):

- Format: `YYYY-MM Type - Entity.extension`
- Example: `2025-06 Bank Statement - Chase Checking.pdf`
- Example: `2023-12 W2 - Acme Corp.pdf`

**Ongoing agreements** (contracts, policies):

- Format: `YYYY-MM Type - Entity.extension`
- Example: `2025-01 Service Agreement - Internet Provider.pdf`

**Appointments/visits**:

- Format: `YYYY-MM-DD Type - Provider/Location.extension`
- Example: `2025-06-13 Dental Visit - Dr Johnson.pdf`

### Creative/Project Files

**Date as supplementary** (photos, projects, creative work):

- Format: `Description - Date.extension` or `Description - Context Date.extension`
- Example: `Vacation Photos - Hawaii 2025.jpg`
- Example: `Website Redesign - Draft 2025-06.pdf`
- Example: `Company Logo 2025.png`

**Evergreen content** (manuals, references):

- Format: `Type - Name/Description.extension`
- Example: `Product Manual - Widget Pro.pdf`

## Key Principles

- **ISO 8601 dates**: YYYY-MM-DD (specific dates) or YYYY-MM (monthly/annual)
- **Date placement**: Start for time-critical sorting; end for contextual info
- **Remove**: Technical metadata (1080p, WEB-DL), problematic characters (`:*?"<>|#%&`)
- **Keep**: Scannable and sortable filenames

## Process

1. Analyze files using OCR, text extraction, vision analysis, filename patterns
2. Present preview table: "Original Filename" | "New Filename"
3. Show up to 15 files if many present
4. Note any files that couldn't be analyzed
5. Wait for confirmation before renaming

If content unclear: make best guess from filename, clean up existing name, or leave unchanged with note.

---

## TV Episode Mode

For TV show files, use standardized Plex/media manager format.

### Convention

- **Format**: `Show Name - sXXeYY - Episode Title.extension`
- **Season/Episode**: Always use two digits and lowercase (e.g., s01e05 instead of S1E5)
- **Clean up**: Remove release group tags, quality markers (1080p, x264), and unnecessary technical metadata

### Process

1. List the files in the target directory or use the provided list
2. Extract the Show Name, Season, and Episode from the existing filenames
3. Propose a preview table: "Original" | "Proposed"
4. Wait for confirmation before executing the rename

If the episode title cannot be determined, use `Show Name - sXXeYY.extension`.

Overview

This skill analyzes file contents and proposes context-aware, standardized filenames to make archives scannable and sortable. It applies date-first conventions for transactional or periodic documents and content-first conventions for creative or evergreen files. The skill can handle single files, lists of files, or entire folders and presents a safe preview before any rename is applied.

How this skill works

It inspects files using text extraction, OCR, and basic vision analysis, supplemented by existing filename patterns and metadata. Based on detected document type it suggests names using ISO 8601 date formats, entity and item descriptors, or media conventions (including TV episode mode). The skill returns a preview table of original vs proposed names, flags items it couldn’t analyze, and waits for user confirmation before renaming.

When to use it

  • Organizing mixed downloads with inconsistent, messy filenames
  • Standardizing receipts, invoices, bank statements, and periodic reports
  • Preparing creative projects, photos, and drafts for archiving
  • Renaming large media folders to Plex-friendly TV episode format
  • Cleaning filenames before backup or version control ingestion

Best practices

  • Prefer ISO 8601 dates (YYYY-MM-DD or YYYY-MM) for time-sensitive files
  • Put the date at the start for transactional items and at the end for creative works
  • Remove technical metadata and problematic characters (:*?"<>|#%&)
  • Limit previews to 15 files at once and note un-analyzable files
  • Confirm all proposed changes before executing bulk renames

Example use cases

  • Rename a downloads folder full of mixed invoices and receipts into YYYY-MM-DD Entity Type - Details.pdf
  • Convert scattered project drafts into Description - Date or Description - Context Date for easy lookup
  • Standardize recurring statements to YYYY-MM Entity - Type for monthly archives
  • Clean TV rips to 'Show Name - sXXeYY - Episode Title.extension' for media servers
  • Tidy a photo collection to 'Vacation Photos - Location YYYY' or 'Event - YYYY-MM-DD'

FAQ

What happens if the skill can’t read a file?

It flags the file as unanalyzable, suggests a best-effort filename based on the existing name, or leaves it unchanged with a note for manual review.

Will it actually rename files immediately?

No. The skill always presents a preview table and waits for explicit confirmation before performing any renames.