How do I install the Smart Rename skill?

Run npx skillmds@latest add tomevault-io/smart-rename 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 Smart Rename safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Smart Rename?

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 Smart Rename free to use?

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

Who published Smart Rename?

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

Smart Rename by tomevault-io — Agent Skill

Name: Smart Rename
Author: tomevault-io

Smart Rename

Content-aware file renamer for macOS. Right-click any image / video / PDF / Word / markdown / folder → AI generates a meaningful Chinese filename. Use when user says "改名 / 重命名 / 整理文件夹 / 给文件起名". This skill assumes Smart Rename is installed (see https://github.com/<owner>/smart-rename). Use when this capability is needed.

tomevault-io Updated Sep 17, 2026

File contents

Smart Rename — Claude Skill

Smart Rename is a local CLI that uses Google Gemini Vision/Text to generate meaningful filenames. Files are renamed to <content-words>_<YYYY-MM-DD>.<ext>.

The renaming logic runs locally — Claude never sees the file content. Claude only orchestrates: ask the user which paths, call the CLI, report back.

When to use

"把 ~/Downloads 的图片都改个名字"
"整理这个文件夹的 PDF"
"给这堆视频起个有意义的名字"
"重命名 / 改名 / rename"

Prerequisites

macOS only
~/.local/bin/smart-rename exists (run which smart-rename)
API key configured (run smart-rename --doctor to verify)

If not installed, point user to the install script:

git clone https://github.com/<owner>/smart-rename.git
cd smart-rename && ./install.sh
smart-rename --setup

How to drive it

Claude should call the CLI directly via the Bash tool. Do not implement renaming logic inside Claude — that wastes tokens.

Step 1 — Preview

smart-rename --preview <path1> <path2> ... > /tmp/sr-plan.json

The CLI returns JSON like:

[
  {"old": "/Users/x/IMG_001.jpg", "new": "/Users/x/京都岚山_2026-04-25.jpg", "status": "ok"},
  {"old": "/Users/x/bad.xyz", "new": null, "status": "error", "error": "..."}
]

Step 2 — Show plan to user

Read the JSON and display each rename in a friendly format:

京都岚山_2026-04-25.jpg  ← IMG_001.jpg

Ask the user to confirm.

Step 3 — Apply

smart-rename --apply /tmp/sr-plan.json

Prints a log path. Files are renamed atomically.

Step 4 — If user wants to undo

smart-rename --undo

Restores the most recent rename batch.

Supported file types

Type	Extensions
Image	jpg, jpeg, png, heic, webp, gif
Video	mp4, mov, m4v, mkv, avi, webm
Document	pdf, docx, doc, rtf, odt
Text	md, markdown, txt, csv, json, xml, html
Folder	(any directory)

Two parallel trigger paths

Users can also trigger rename without Claude:

Right-click in Finder → Quick Actions → "改名 (Smart Rename)"
⌥⌘R (if Hammerspoon module installed)

These use the same CLI under the hood. Claude is just one of several front-ends.

Don't

Don't read the file content yourself and try to name it. The CLI does this with Gemini Flash, which is far cheaper than Claude.
Don't suggest names without running --preview first.
Don't apply without showing the user the preview.

Source: Jane-xiaoer/smart-rename — distributed by TomeVault.

---name: smart-renamedescription: Content-aware file renamer for macOS. Right-click any image / video / PDF / Word / markdown / folder → AI generates a meaningful Chinese filename. Use when user says "改名 / 重命名 / 整理文件夹 / 给文件起名". This skill assumes Smart Rename is installed (see https://github.com/<owner>/smart-rename). Use when this capability is needed.---# Smart Rename — Claude SkillSmart Rename is a local CLI that uses Google Gemini Vision/Text to generatemeaningful filenames. Files are renamed to `<content-words>_<YYYY-MM-DD>.<ext>`.**The renaming logic runs locally — Claude never sees the file content.**Claude only orchestrates: ask the user which paths, call the CLI, report back.## When to use- "把 ~/Downloads 的图片都改个名字"- "整理这个文件夹的 PDF"- "给这堆视频起个有意义的名字"- "重命名 / 改名 / rename"## Prerequisites- macOS only- `~/.local/bin/smart-rename` exists (run `which smart-rename`)- API key configured (run `smart-rename --doctor` to verify)If not installed, point user to the install script:```bashgit clone https://github.com/<owner>/smart-rename.gitcd smart-rename && ./install.shsmart-rename --setup```## How to drive itClaude should call the CLI directly via the Bash tool. **Do not implementrenaming logic inside Claude** — that wastes tokens.### Step 1 — Preview```bashsmart-rename --preview <path1> <path2> ... > /tmp/sr-plan.json```The CLI returns JSON like:```json[ {"old": "/Users/x/IMG_001.jpg", "new": "/Users/x/京都岚山_2026-04-25.jpg", "status": "ok"}, {"old": "/Users/x/bad.xyz", "new": null, "status": "error", "error": "..."}]```### Step 2 — Show plan to userRead the JSON and display each rename in a friendly format:```京都岚山_2026-04-25.jpg ← IMG_001.jpg```Ask the user to confirm.### Step 3 — Apply```bashsmart-rename --apply /tmp/sr-plan.json```Prints a log path. Files are renamed atomically.### Step 4 — If user wants to undo```bashsmart-rename --undo```Restores the most recent rename batch.## Supported file types| Type | Extensions ||------|------------|| Image | jpg, jpeg, png, heic, webp, gif || Video | mp4, mov, m4v, mkv, avi, webm || Document | pdf, docx, doc, rtf, odt || Text | md, markdown, txt, csv, json, xml, html || Folder | (any directory) |## Two parallel trigger pathsUsers can also trigger rename without Claude:1. **Right-click in Finder** → Quick Actions → "改名 (Smart Rename)"2. **⌥⌘R** (if Hammerspoon module installed)These use the same CLI under the hood. Claude is just one of severalfront-ends.## Don't- Don't read the file content yourself and try to name it. The CLI does this with Gemini Flash, which is far cheaper than Claude.- Don't suggest names without running `--preview` first.- Don't apply without showing the user the preview.---> Source: [Jane-xiaoer/smart-rename](https://github.com/Jane-xiaoer/smart-rename) — distributed by [TomeVault](https://tomevault.io).

Frequently asked questions