zhongwei/gh-kivilaid-plugin-marketplace-organization-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:32:18 +08:00
commit d9c25ac00e
5 changed files with 943 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

433
skills/file-organizer/SKILL.md Normal file
View File

@@ -0,0 +1,433 @@
---
name: file-organizer
description: Intelligently organizes your files and folders across your computer by understanding context, finding duplicates, suggesting better structures, and automating cleanup tasks. Reduces cognitive load and keeps your digital workspace tidy without manual effort.
---
# File Organizer
This skill acts as your personal organization assistant, helping you maintain a clean, logical file structure across your computer without the mental overhead of constant manual organization.
## When to Use This Skill
- Your Downloads folder is a chaotic mess
- You can't find files because they're scattered everywhere
- You have duplicate files taking up space
- Your folder structure doesn't make sense anymore
- You want to establish better organization habits
- You're starting a new project and need a good structure
- You're cleaning up before archiving old projects
## What This Skill Does
1. **Analyzes Current Structure**: Reviews your folders and files to understand what you have
2. **Finds Duplicates**: Identifies duplicate files across your system
3. **Suggests Organization**: Proposes logical folder structures based on your content
4. **Automates Cleanup**: Moves, renames, and organizes files with your approval
5. **Maintains Context**: Makes smart decisions based on file types, dates, and content
6. **Reduces Clutter**: Identifies old files you probably don't need anymore
## How to Use
### From Your Home Directory
```
cd ~
```
Then run Claude Code and ask for help:
```
Help me organize my Downloads folder
```
```
Find duplicate files in my Documents folder
```
```
Review my project directories and suggest improvements
```
### Specific Organization Tasks
```
Organize these downloads into proper folders based on what they are
```
```
Find duplicate files and help me decide which to keep
```
```
Clean up old files I haven't touched in 6+ months
```
```
Create a better folder structure for my [work/projects/photos/etc]
```
## Instructions
When a user requests file organization help:
1. **Understand the Scope**
Ask clarifying questions:
- Which directory needs organization? (Downloads, Documents, entire home folder?)
- What's the main problem? (Can't find things, duplicates, too messy, no structure?)
- Any files or folders to avoid? (Current projects, sensitive data?)
- How aggressively to organize? (Conservative vs. comprehensive cleanup)
2. **Analyze Current State**
Review the target directory:
```bash
# Get overview of current structure
ls -la [target_directory]
# Check file types and sizes
find [target_directory] -type f -exec file {} \; | head -20
# Identify largest files
du -sh [target_directory]/* | sort -rh | head -20
# Count file types
find [target_directory] -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn
```
Summarize findings:
- Total files and folders
- File type breakdown
- Size distribution
- Date ranges
- Obvious organization issues
3. **Identify Organization Patterns**
Based on the files, determine logical groupings:
**By Type**:
- Documents (PDFs, DOCX, TXT)
- Images (JPG, PNG, SVG)
- Videos (MP4, MOV)
- Archives (ZIP, TAR, DMG)
- Code/Projects (directories with code)
- Spreadsheets (XLSX, CSV)
- Presentations (PPTX, KEY)
**By Purpose**:
- Work vs. Personal
- Active vs. Archive
- Project-specific
- Reference materials
- Temporary/scratch files
**By Date**:
- Current year/month
- Previous years
- Very old (archive candidates)
4. **Find Duplicates**
When requested, search for duplicates:
```bash
# Find exact duplicates by hash
find [directory] -type f -exec md5 {} \; | sort | uniq -d
# Find files with same name
find [directory] -type f -printf '%f\n' | sort | uniq -d
# Find similar-sized files
find [directory] -type f -printf '%s %p\n' | sort -n
```
For each set of duplicates:
- Show all file paths
- Display sizes and modification dates
- Recommend which to keep (usually newest or best-named)
- **Important**: Always ask for confirmation before deleting
5. **Propose Organization Plan**
Present a clear plan before making changes:
```markdown
# Organization Plan for [Directory]
## Current State
- X files across Y folders
- [Size] total
- File types: [breakdown]
- Issues: [list problems]
## Proposed Structure
```
[Directory]/
├── Work/
│ ├── Projects/
│ ├── Documents/
│ └── Archive/
├── Personal/
│ ├── Photos/
│ ├── Documents/
│ └── Media/
└── Downloads/
├── To-Sort/
└── Archive/
```
## Changes I'll Make
1. **Create new folders**: [list]
2. **Move files**:
- X PDFs → Work/Documents/
- Y images → Personal/Photos/
- Z old files → Archive/
3. **Rename files**: [any renaming patterns]
4. **Delete**: [duplicates or trash files]
## Files Needing Your Decision
- [List any files you're unsure about]
Ready to proceed? (yes/no/modify)
```
6. **Execute Organization**
After approval, organize systematically:
```bash
# Create folder structure
mkdir -p "path/to/new/folders"
# Move files with clear logging
mv "old/path/file.pdf" "new/path/file.pdf"
# Rename files with consistent patterns
# Example: "YYYY-MM-DD - Description.ext"
```
**Important Rules**:
- Always confirm before deleting anything
- Log all moves for potential undo
- Preserve original modification dates
- Handle filename conflicts gracefully
- Stop and ask if you encounter unexpected situations
7. **Provide Summary and Maintenance Tips**
After organizing:
```markdown
# Organization Complete! ✨
## What Changed
- Created [X] new folders
- Organized [Y] files
- Freed [Z] GB by removing duplicates
- Archived [W] old files
## New Structure
[Show the new folder tree]
## Maintenance Tips
To keep this organized:
1. **Weekly**: Sort new downloads
2. **Monthly**: Review and archive completed projects
3. **Quarterly**: Check for new duplicates
4. **Yearly**: Archive old files
## Quick Commands for You
```bash
# Find files modified this week
find . -type f -mtime -7
# Sort downloads by type
[custom command for their setup]
# Find duplicates
[custom command]
```
Want to organize another folder?
```
## Examples
### Example 1: Organizing Downloads (From Justin Dielmann)
**User**: "My Downloads folder is a mess with 500+ files. Help me organize it."
**Process**:
1. Analyzes Downloads folder
2. Finds patterns: work docs, personal photos, installers, random PDFs
3. Proposes structure:
- Downloads/
- Work/
- Personal/
- Installers/ (DMG, PKG files)
- Archive/
- ToSort/ (things needing decisions)
4. Asks for confirmation
5. Moves files intelligently based on content and names
6. Results: 500 files → 5 organized folders
### Example 2: Finding and Removing Duplicates
**User**: "Find duplicate files in my Documents and help me decide which to keep."
**Output**:
```markdown
# Found 23 Sets of Duplicates (156 MB total)
## Duplicate Set 1: "proposal.pdf"
- `/Documents/proposal.pdf` (2.3 MB, modified: 2024-03-15)
- `/Documents/old/proposal.pdf` (2.3 MB, modified: 2024-03-15)
- `/Desktop/proposal.pdf` (2.3 MB, modified: 2024-03-10)
**Recommendation**: Keep `/Documents/proposal.pdf` (most recent in correct location)
Delete the other 2 copies?
[Continue for all duplicates...]
```
### Example 3: Restructuring Projects Folder
**User**: "Review my ~/Projects directory and suggest improvements."
**Output**:
```markdown
# Analysis of ~/Projects
## Current Structure Issues
- Mix of active and archived projects (3+ years old)
- No consistent naming convention
- Some projects at root, others in random subfolders
- Duplicate folders (project-name, project-name-old, project-name-v2)
## Proposed Structure
```
Projects/
├── Active/
│ ├── client-work/
│ ├── side-projects/
│ └── learning/
├── Archive/
│ ├── 2022/
│ ├── 2023/
│ └── 2024/
└── Templates/
```
## Specific Changes
1. Move 12 projects not touched since 2022 → Archive/
2. Consolidate 4 duplicate project folders
3. Rename projects to consistent format: "client-name-project-name"
4. Create Archive for old work
Want me to implement this?
```
### Example 4: Organizing Photos by Date
**User**: "Organize my photo folders by year and month."
**Output**: Creates structure like:
```
Photos/
├── 2023/
│ ├── 01-January/
│ ├── 02-February/
│ └── ...
├── 2024/
│ ├── 01-January/
│ └── ...
└── Unsorted/
```
Then moves photos based on EXIF data or file modification dates.
## Common Organization Tasks
### Downloads Cleanup
```
Organize my Downloads folder - move documents to Documents,
images to Pictures, keep installers separate, and archive files
older than 3 months.
```
### Project Organization
```
Review my Projects folder structure and help me separate active
projects from old ones I should archive.
```
### Duplicate Removal
```
Find all duplicate files in my Documents folder and help me
decide which ones to keep.
```
### Desktop Cleanup
```
My Desktop is covered in files. Help me organize everything into
my Documents folder properly.
```
### Photo Organization
```
Organize all photos in this folder by date (year/month) based
on when they were taken.
```
### Work/Personal Separation
```
Help me separate my work files from personal files across my
Documents folder.
```
## Pro Tips
1. **Start Small**: Begin with one messy folder (like Downloads) to build trust
2. **Regular Maintenance**: Run weekly cleanup on Downloads
3. **Consistent Naming**: Use "YYYY-MM-DD - Description" format for important files
4. **Archive Aggressively**: Move old projects to Archive instead of deleting
5. **Keep Active Separate**: Maintain clear boundaries between active and archived work
6. **Trust the Process**: Let Claude handle the cognitive load of where things go
## Best Practices
### Folder Naming
- Use clear, descriptive names
- Avoid spaces (use hyphens or underscores)
- Be specific: "client-proposals" not "docs"
- Use prefixes for ordering: "01-current", "02-archive"
### File Naming
- Include dates: "2024-10-17-meeting-notes.md"
- Be descriptive: "q3-financial-report.xlsx"
- Avoid version numbers in names (use version control instead)
- Remove download artifacts: "document-final-v2 (1).pdf" → "document.pdf"
### When to Archive
- Projects not touched in 6+ months
- Completed work that might be referenced later
- Old versions after migration to new systems
- Files you're hesitant to delete (archive first)
## Related Use Cases
- Setting up organization for a new computer
- Preparing files for backup/archiving
- Cleaning up before storage cleanup
- Organizing shared team folders
- Structuring new project directories

446
skills/invoice-organizer/SKILL.md Normal file
View File

@@ -0,0 +1,446 @@
---
name: invoice-organizer
description: Automatically organizes invoices and receipts for tax preparation by reading messy files, extracting key information, renaming them consistently, and sorting them into logical folders. Turns hours of manual bookkeeping into minutes of automated organization.
---
# Invoice Organizer
This skill transforms chaotic folders of invoices, receipts, and financial documents into a clean, tax-ready filing system without manual effort.
## When to Use This Skill
- Preparing for tax season and need organized records
- Managing business expenses across multiple vendors
- Organizing receipts from a messy folder or email downloads
- Setting up automated invoice filing for ongoing bookkeeping
- Archiving financial records by year or category
- Reconciling expenses for reimbursement
- Preparing documentation for accountants
## What This Skill Does
1. **Reads Invoice Content**: Extracts information from PDFs, images, and documents:
- Vendor/company name
- Invoice number
- Date
- Amount
- Product or service description
- Payment method
2. **Renames Files Consistently**: Creates standardized filenames:
- Format: `YYYY-MM-DD Vendor - Invoice - ProductOrService.pdf`
- Examples: `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`
3. **Organizes by Category**: Sorts into logical folders:
- By vendor
- By expense category (software, office, travel, etc.)
- By time period (year, quarter, month)
- By tax category (deductible, personal, etc.)
4. **Handles Multiple Formats**: Works with:
- PDF invoices
- Scanned receipts (JPG, PNG)
- Email attachments
- Screenshots
- Bank statements
5. **Maintains Originals**: Preserves original files while organizing copies
## How to Use
### Basic Usage
Navigate to your messy invoice folder:
```
cd ~/Desktop/receipts-to-sort
```
Then ask Claude Code:
```
Organize these invoices for taxes
```
Or more specifically:
```
Read all invoices in this folder, rename them to
"YYYY-MM-DD Vendor - Invoice - Product.pdf" format,
and organize them by vendor
```
### Advanced Organization
```
Organize these invoices:
1. Extract date, vendor, and description from each file
2. Rename to standard format
3. Sort into folders by expense category (Software, Office, Travel, etc.)
4. Create a CSV spreadsheet with all invoice details for my accountant
```
## Instructions
When a user requests invoice organization:
1. **Scan the Folder**
Identify all invoice files:
```bash
# Find all invoice-related files
find . -type f \( -name "*.pdf" -o -name "*.jpg" -o -name "*.png" \) -print
```
Report findings:
- Total number of files
- File types
- Date range (if discernible from names)
- Current organization (or lack thereof)
2. **Extract Information from Each File**
For each invoice, extract:
**From PDF invoices**:
- Use text extraction to read invoice content
- Look for common patterns:
- "Invoice Date:", "Date:", "Issued:"
- "Invoice #:", "Invoice Number:"
- Company name (usually at top)
- "Amount Due:", "Total:", "Amount:"
- "Description:", "Service:", "Product:"
**From image receipts**:
- Read visible text from images
- Identify vendor name (often at top)
- Look for date (common formats)
- Find total amount
**Fallback for unclear files**:
- Use filename clues
- Check file creation/modification date
- Flag for manual review if critical info missing
3. **Determine Organization Strategy**
Ask user preference if not specified:
```markdown
I found [X] invoices from [date range].
How would you like them organized?
1. **By Vendor** (Adobe/, Amazon/, Stripe/, etc.)
2. **By Category** (Software/, Office Supplies/, Travel/, etc.)
3. **By Date** (2024/Q1/, 2024/Q2/, etc.)
4. **By Tax Category** (Deductible/, Personal/, etc.)
5. **Custom** (describe your structure)
Or I can use a default structure: Year/Category/Vendor
```
4. **Create Standardized Filename**
For each invoice, create a filename following this pattern:
```
YYYY-MM-DD Vendor - Invoice - Description.ext
```
Examples:
- `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`
- `2024-01-10 Amazon - Receipt - Office Supplies.pdf`
- `2023-12-01 Stripe - Invoice - Monthly Payment Processing.pdf`
**Filename Best Practices**:
- Remove special characters except hyphens
- Capitalize vendor names properly
- Keep descriptions concise but meaningful
- Use consistent date format (YYYY-MM-DD) for sorting
- Preserve original file extension
5. **Execute Organization**
Before moving files, show the plan:
```markdown
# Organization Plan
## Proposed Structure
```
Invoices/
├── 2023/
│ ├── Software/
│ │ ├── Adobe/
│ │ └── Microsoft/
│ ├── Services/
│ └── Office/
└── 2024/
├── Software/
├── Services/
└── Office/
```
## Sample Changes
Before: `invoice_adobe_march.pdf`
After: `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`
Location: `Invoices/2024/Software/Adobe/`
Before: `IMG_2847.jpg`
After: `2024-02-10 Staples - Receipt - Office Supplies.jpg`
Location: `Invoices/2024/Office/Staples/`
Process [X] files? (yes/no)
```
After approval:
```bash
# Create folder structure
mkdir -p "Invoices/2024/Software/Adobe"
# Copy (don't move) to preserve originals
cp "original.pdf" "Invoices/2024/Software/Adobe/2024-03-15 Adobe - Invoice - Creative Cloud.pdf"
# Or move if user prefers
mv "original.pdf" "new/path/standardized-name.pdf"
```
6. **Generate Summary Report**
Create a CSV file with all invoice details:
```csv
Date,Vendor,Invoice Number,Description,Amount,Category,File Path
2024-03-15,Adobe,INV-12345,Creative Cloud,52.99,Software,Invoices/2024/Software/Adobe/2024-03-15 Adobe - Invoice - Creative Cloud.pdf
2024-03-10,Amazon,123-4567890-1234567,Office Supplies,127.45,Office,Invoices/2024/Office/Amazon/2024-03-10 Amazon - Receipt - Office Supplies.pdf
...
```
This CSV is useful for:
- Importing into accounting software
- Sharing with accountants
- Expense tracking and reporting
- Tax preparation
7. **Provide Completion Summary**
```markdown
# Organization Complete! 📊
## Summary
- **Processed**: [X] invoices
- **Date range**: [earliest] to [latest]
- **Total amount**: $[sum] (if amounts extracted)
- **Vendors**: [Y] unique vendors
## New Structure
```
Invoices/
├── 2024/ (45 files)
│ ├── Software/ (23 files)
│ ├── Services/ (12 files)
│ └── Office/ (10 files)
└── 2023/ (12 files)
```
## Files Created
- `/Invoices/` - Organized invoices
- `/Invoices/invoice-summary.csv` - Spreadsheet for accounting
- `/Invoices/originals/` - Original files (if copied)
## Files Needing Review
[List any files where information couldn't be extracted completely]
## Next Steps
1. Review the `invoice-summary.csv` file
2. Check files in "Needs Review" folder
3. Import CSV into your accounting software
4. Set up auto-organization for future invoices
Ready for tax season! 🎉
```
## Examples
### Example 1: Tax Preparation (From Martin Merschroth)
**User**: "I have a messy folder of invoices for taxes. Sort them and rename properly."
**Process**:
1. Scans folder: finds 147 PDFs and images
2. Reads each invoice to extract:
- Date
- Vendor name
- Invoice number
- Product/service description
3. Renames all files: `YYYY-MM-DD Vendor - Invoice - Product.pdf`
4. Organizes into: `2024/Software/`, `2024/Travel/`, etc.
5. Creates `invoice-summary.csv` for accountant
6. Result: Tax-ready organized invoices in minutes
### Example 2: Monthly Expense Reconciliation
**User**: "Organize my business receipts from last month by category."
**Output**:
```markdown
# March 2024 Receipts Organized
## By Category
- Software & Tools: $847.32 (12 invoices)
- Office Supplies: $234.18 (8 receipts)
- Travel & Meals: $1,456.90 (15 receipts)
- Professional Services: $2,500.00 (3 invoices)
Total: $5,038.40
All receipts renamed and filed in:
`Business-Receipts/2024/03-March/[Category]/`
CSV export: `march-2024-expenses.csv`
```
### Example 3: Multi-Year Archive
**User**: "I have 3 years of random invoices. Organize them by year, then by vendor."
**Output**: Creates structure:
```
Invoices/
├── 2022/
│ ├── Adobe/
│ ├── Amazon/
│ └── ...
├── 2023/
│ ├── Adobe/
│ ├── Amazon/
│ └── ...
└── 2024/
├── Adobe/
├── Amazon/
└── ...
```
Each file properly renamed with date and description.
### Example 4: Email Downloads Cleanup
**User**: "I download invoices from Gmail. They're all named 'invoice.pdf', 'invoice(1).pdf', etc. Fix this mess."
**Output**:
```markdown
Found 89 files all named "invoice*.pdf"
Reading each file to extract real information...
Renamed examples:
- invoice.pdf → 2024-03-15 Shopify - Invoice - Monthly Subscription.pdf
- invoice(1).pdf → 2024-03-14 Google - Invoice - Workspace.pdf
- invoice(2).pdf → 2024-03-10 Netlify - Invoice - Pro Plan.pdf
All files renamed and organized by vendor.
```
## Common Organization Patterns
### By Vendor (Simple)
```
Invoices/
├── Adobe/
├── Amazon/
├── Google/
└── Microsoft/
```
### By Year and Category (Tax-Friendly)
```
Invoices/
├── 2023/
│ ├── Software/
│ ├── Hardware/
│ ├── Services/
│ └── Travel/
└── 2024/
└── ...
```
### By Quarter (Detailed Tracking)
```
Invoices/
├── 2024/
│ ├── Q1/
│ │ ├── Software/
│ │ ├── Office/
│ │ └── Travel/
│ └── Q2/
│ └── ...
```
### By Tax Category (Accountant-Ready)
```
Invoices/
├── Deductible/
│ ├── Software/
│ ├── Office/
│ └── Professional-Services/
├── Partially-Deductible/
│ └── Meals-Travel/
└── Personal/
```
## Automation Setup
For ongoing organization:
```
Create a script that watches my ~/Downloads/invoices folder
and auto-organizes any new invoice files using our standard
naming and folder structure.
```
This creates a persistent solution that organizes invoices as they arrive.
## Pro Tips
1. **Scan emails to PDF**: Use Preview or similar to save email invoices as PDFs first
2. **Consistent downloads**: Save all invoices to one folder for batch processing
3. **Monthly routine**: Organize invoices monthly, not annually
4. **Backup originals**: Keep original files before reorganizing
5. **Include amounts in CSV**: Useful for budget tracking
6. **Tag by deductibility**: Note which expenses are tax-deductible
7. **Keep receipts 7 years**: Standard audit period
## Handling Special Cases
### Missing Information
If date/vendor can't be extracted:
- Flag file for manual review
- Use file modification date as fallback
- Create "Needs-Review/" folder
### Duplicate Invoices
If same invoice appears multiple times:
- Compare file hashes
- Keep highest quality version
- Note duplicates in summary
### Multi-Page Invoices
For invoices split across files:
- Merge PDFs if needed
- Use consistent naming for parts
- Note in CSV if invoice is split
### Non-Standard Formats
For unusual receipt formats:
- Extract what's possible
- Standardize what you can
- Flag for review if critical info missing
## Related Use Cases
- Creating expense reports for reimbursement
- Organizing bank statements
- Managing vendor contracts
- Archiving old financial records
- Preparing for audits
- Tracking subscription costs over time