Skip to content

improve file-organizer skill structure + add skill-review CI #313

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Bap (fernandezbaptiste) wants to merge 1 commit into
base: main
Choose a base branch
from
Open

improve file-organizer skill structure + add skill-review CI #313

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .github/workflows/skill-review.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
name: Skill Review
on:
pull_request:
paths: ['**/SKILL.md']

jobs:
review:
runs-on: ubuntu-latest
permissions:
pull-requests: write
contents: read
steps:
- uses: actions/checkout@v4
- uses: tesslio/skill-review@14b47c8420ff9ac9a12c30ed4b89ce0e9d0355ae # main
260 changes: 36 additions & 224 deletions examples/skills/file-organizer/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,243 +1,55 @@
---
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.
description: >
Scan directories, find duplicate files by hash, categorize by type/date/purpose,
and reorganize with a confirmation-gated plan. Use when the user says "organize
my files", "clean up Downloads", "find duplicates", "declutter folders",
"file management", or "sort files".
---

# 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.
**SAFETY: Always confirm with the user before moving or deleting any files. Log all operations so they can be undone.**

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

**SAFETY WARNING: This skill involves moving and deleting files. You MUST ALWAYS explicitly ask for user confirmation before deleting any files. When moving large numbers of files, ensure you have a way to undo or log the operations.**

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 to understand:
- 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 using available system tools.

**Note**: Avoid using platform-specific flags (like `find -printf` or `md5` on Linux/Windows) unless you are sure of the environment.

Strategies:
- **Exact Duplicates**: Compare file hashes (use `shasum`, `cksum`, or `md5sum` depending on OS).
- **Name Duplicates**: Find files with the same filename.
- **Size Duplicates**: Find files with identical file sizes as a first pass.

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]
## Workflow

1. **Scope** — ask which directory, what problem (duplicates, messy, no structure), and any folders to skip
2. **Analyze** — survey target directory:
```bash
find ~/Downloads -maxdepth 1 -type f | wc -l # file count
find ~/Downloads -maxdepth 1 -type f -name "*.pdf" | wc -l # by type
du -sh ~/Downloads # total size
```
3. **Find duplicates** (if requested):
```bash
find . -type f -exec shasum {} + | sort | uniq -D -w 40
```
For each duplicate set: show paths, sizes, dates. Recommend keeping the newest in the best-named location. **Always ask before deleting.**
4. **Propose plan** — present before making any changes:
```
## Proposed Structure

[Directory]/
Downloads/
├── Work/
│ ├── Projects/
│ ├── Documents/
│ └── Archive/
├── Personal/
│ ├── Photos/
│ ├── Documents/
│ └── Media/
└── Downloads/
├── To-Sort/
├── Installers/
└── 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]
## Changes
1. Create 4 folders
2. Move 120 PDFs → Work/
3. Move 45 images → Personal/
4. Move 30 DMG/PKG → Installers/
5. Delete 12 duplicate files (saving 89 MB)

Ready to proceed? (yes/no/modify)
```
5. **Execute** — move files, log every operation, report results

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

## 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"
## Grouping Strategies

### When to Archive
| Strategy | Use when | Example categories |
|----------|----------|--------------------|
| By type | mixed file dump (Downloads) | Documents, Images, Videos, Archives, Code |
| By purpose | project-heavy directory | Work, Personal, Reference, Archive |
| By date | long-accumulated folder | Current year, Previous years, 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)