How do I install the File Sorter skill?

Run npx skillmds@latest add bahayonghang/file-sorter in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is File Sorter safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with File Sorter?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is File Sorter free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published File Sorter?

bahayonghang (@bahayonghang) published this skill. Their other Agent Skills are listed on their SkillMD profile.

File Sorter by bahayonghang — Agent Skill

Name: File Sorter
Rating: 4.2 (5 reviews)
Author: bahayonghang

File Sorter

Use when the user wants to categorize, sort, organize, or suggest renames for files in a local folder such as Downloads, or for files that share one parent directory. Builds a review plan with stable file-family categories, optional whitelist, project-root protection, and dry-run apply; moves or renames only after explicit approval of that plan. Use for 整理文件, 分类归档, Downloads 整理, 重命名建议, 审阅后再移动. Do not use for Git worktree isolation, Windows process cleanup, repository source-layout refactors, duplicate deletion, cloud-drive sync, or installing the AI File Sorter desktop app.

bahayonghang 983d0a5 20 files · 94.3 KB Updated Sep 10, 2026

File contents

In the commands below, <skill-dir> is this skill's base directory, announced when the skill loads. Substitute the literal path. On Windows, py -3 may replace python.

Default: scan and assemble a review plan. --execute is forbidden until the user approves the shown plan_id in this turn.

Routing

Local folder / same-parent files, categorize, organize, rename suggestions: this skill.
Windows dev process cleanup: windows-dev-process-cleanup.
Git worktree create/list/remove: git-worktree.
Commit: git-commit.
Repository source-layout refactors, duplicate deletion, Drive sync, PARA cabinets: refuse.

Workflow

Scan (absolute --root only):

python "<skill-dir>/scripts/file_sorter.py" scan --root <abs> [--recursive] [--output <scan.json>]

If ok_to_scan is false, report skipped and stop.

Propose category / subcategory / optional suggested_name from taxonomy.md. Use document excerpts only when the name is vague (max about 8000 characters). Use an image description only when the host already has vision. Screenshots describe on-screen content; do not label ordinary images as Installers or Operating Systems. Do not compute target_dir.
Assemble:

python "<skill-dir>/scripts/file_sorter.py" assemble-plan --scan <scan.json> --proposals <proposals.json> [--mode more-consistent|more-refined] [--operation categorize|rename|categorize-and-rename] [--whitelist <whitelist.json>] [--output <plan.json>]

Default mode is more-consistent. Default operation is categorize.

Show plan_id, items, rejected, skipped. Preview apply:

python "<skill-dir>/scripts/file_sorter.py" apply --plan <plan.json>

After this-turn approval of that plan_id:

python "<skill-dir>/scripts/file_sorter.py" apply --plan <plan.json> --execute

Undo with the sidecar from undo_path only after showing it and getting approval:

python "<skill-dir>/scripts/file_sorter.py" undo --undo <plan.undo.json> --execute

Do not call mv, Move-Item, or delete user files. Helper default is dry-run.

Output

Report plan_id, ok_to_apply, destination paths, skipped reasons, and whether apply was dry-run or executed. Mark install proof, provider comparison, and human blind review as missing evidence.

Resources

taxonomy.md
scan-safety.md
review-apply.md
naming.md

---name: file-sorterdescription: Use when the user wants to categorize, sort, organize, or suggest renames for files in a local folder such as Downloads, or for files that share one parent directory. Builds a review plan with stable file-family categories, optional whitelist, project-root protection, and dry-run apply; moves or renames only after explicit approval of that plan. Use for 整理文件, 分类归档, Downloads 整理, 重命名建议, 审阅后再移动. Do not use for Git worktree isolation, Windows process cleanup, repository source-layout refactors, duplicate deletion, cloud-drive sync, or installing the AI File Sorter desktop app.---In the commands below, `<skill-dir>` is this skill's base directory, announced when the skill loads. Substitute the literal path. On Windows, `py -3` may replace `python`.Default: scan and assemble a review plan. `--execute` is forbidden until the user approves the shown `plan_id` in this turn.## Routing- Local folder / same-parent files, categorize, organize, rename suggestions: this skill.- Windows dev process cleanup: `windows-dev-process-cleanup`.- Git worktree create/list/remove: `git-worktree`.- Commit: `git-commit`.- Repository source-layout refactors, duplicate deletion, Drive sync, PARA cabinets: refuse.## Workflow1. Scan (absolute `--root` only):```textpython "<skill-dir>/scripts/file_sorter.py" scan --root <abs> [--recursive] [--output <scan.json>]```If `ok_to_scan` is false, report `skipped` and stop.2. Propose `category` / `subcategory` / optional `suggested_name` from [taxonomy.md](references/taxonomy.md). Use document excerpts only when the name is vague (max about 8000 characters). Use an image description only when the host already has vision. Screenshots describe on-screen content; do not label ordinary images as Installers or Operating Systems. Do not compute `target_dir`.3. Assemble:```textpython "<skill-dir>/scripts/file_sorter.py" assemble-plan --scan <scan.json> --proposals <proposals.json> [--mode more-consistent|more-refined] [--operation categorize|rename|categorize-and-rename] [--whitelist <whitelist.json>] [--output <plan.json>]```Default mode is `more-consistent`. Default operation is `categorize`.4. Show `plan_id`, items, rejected, skipped. Preview apply:```textpython "<skill-dir>/scripts/file_sorter.py" apply --plan <plan.json>```5. After this-turn approval of that `plan_id`:```textpython "<skill-dir>/scripts/file_sorter.py" apply --plan <plan.json> --execute```6. Undo with the sidecar from `undo_path` only after showing it and getting approval:```textpython "<skill-dir>/scripts/file_sorter.py" undo --undo <plan.undo.json> --execute```Do not call `mv`, `Move-Item`, or delete user files. Helper default is dry-run.## OutputReport `plan_id`, `ok_to_apply`, destination paths, skipped reasons, and whether apply was dry-run or executed. Mark install proof, provider comparison, and human blind review as `missing evidence`.## Resources- [taxonomy.md](references/taxonomy.md)- [scan-safety.md](references/scan-safety.md)- [review-apply.md](references/review-apply.md)- [naming.md](references/naming.md)

Frequently asked questions