playbooks

home / skills / nweii / agent-stuff / file-naming

file-naming skill

/skills/file-naming

This skill analyzes file content and proposes intelligent renames using context-aware conventions to improve organization and discoverability.

npx playbooks add skill nweii/agent-stuff --skill file-naming

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

Files (3)
SKILL.md
2.5 KB
---
name: file-naming
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.2"
---

# 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.

**For TV show files**, see [references/tv-episodes.md](references/tv-episodes.md) for Plex/media manager naming conventions.

Overview

This skill analyzes file content and proposes context-aware, standardized filenames to make documents scannable and sortable. It applies date-first conventions for transactional and periodic files and content-first conventions for creative or evergreen items. The goal is cleaner downloads, consistent archives, and easier search and sorting. It presents safe, reversible rename suggestions and waits for confirmation before making changes.

How this skill works

The skill inspects file contents using OCR, text extraction, and basic vision analysis, and also considers existing filename patterns and metadata. It classifies files into transactional/periodic, creative/project, or evergreen categories and generates new names using ISO 8601 dates where appropriate. It returns a preview table mapping original names to proposed names, flags unanalyzable files, and limits previews to 15 items for large folders. It does not rename files until you confirm the suggested changes.

When to use it

  • Organizing a messy Downloads or Desktop folder
  • Standardizing company or personal document archives
  • Preparing files for backup or migration
  • Cleaning up receipts, invoices, and bank statements
  • Renaming creative projects, photos, and design drafts

Best practices

  • Prefer ISO 8601 dates (YYYY-MM-DD or YYYY-MM) for time-sensitive documents
  • Start filenames with the date for transactional/periodic items to enable chronological sorting
  • Use descriptive, content-first names for photos, drafts, and evergreen references
  • Strip technical metadata tokens (1080p, WEB-DL) and problematic characters (:*?"<>|#%&)
  • Review the preview table and confirm renames; keep originals until you’re satisfied

Example use cases

  • Rename a folder of mixed bank statements, receipts, and invoices to YYYY-MM or YYYY-MM-DD formats
  • Clean a downloads folder by turning vague names into content-first titles for creative files
  • Standardize ongoing contracts and policies to YYYY-MM Type - Entity.extension
  • Convert camera roll files into Description - Date.jpg for photo archives
  • Prepare a project folder by renaming drafts and exports to clear, consistent labels

FAQ

What if the file content is unreadable?

If content is unclear the skill makes a best guess from the existing filename and metadata, or it will leave the name unchanged and flag the file for manual review.

Will files be renamed immediately?

No. The skill always shows a preview table and waits for explicit confirmation before applying any renames; this preserves safety and control.