Rename a skill

You named a skill code-review six months ago. It's now mostly about pull request etiquette. You want to call it pr-etiquette. That's a rename:

airskills mv code-review pr-etiquette

That one command:

• Renames the local directory in every detected agent (~/.claude/skills/, ~/.cursor/skills/, ~/.copilot/skills/, and so on)
• Updates the skill's display name on the server
• Updates your local sync state so the next push and pull do the right thing

The skill keeps its history, its commits, its identity, and its owner. Everything inside the skill is unchanged — only the label changes.

What other people see

If anyone has installed your skill via airskills add, their copy keeps working and their airskills pull keeps fetching updates from it — because the CLI tracks the skill by its underlying ID, not its name.

The thing that does change is the name itself. If they — or their AI agent — refer to the skill by name in prompts, scripts, or agent configs ("use the code-review skill"), they'll need to use the new name afterwards. The skill still loads and still updates. Only the label changes.

A polite rename of a widely-used skill is worth a small announcement, so people can update any places they call it by name.

This is the key difference from transfer: rename does not break anyone's CLI sync — the skill remains the same skill, addressable by the same ID. Transfer makes a genuinely new skill in a new place, and the old slug stops resolving entirely.

When to use rename

• The skill grew into a different scope and the old name is misleading
• You're tidying up your personal namespace
• You picked a name in a hurry and want to fix it

When not to use rename

If you're trying to hand your skill over to your organization, or pull an organization skill back to yourself, that's a transfer, not a rename. Renaming will only change the label — it will not change who owns the skill.

Things to know

• The new name must be unique within your account. If you already have a skill called pr-etiquette, the rename fails before anything moves.
• Names follow the standard skill-name rules: lowercase, hyphens, no spaces or special characters.
• The CLI moves the local directories one at a time. If something goes wrong partway through, it tries to revert any moves it already made so you do not end up half-renamed.
• A URL pointing at the old name (for example, a link in a Slack message) will stop resolving after the rename. The skill still exists — just at the new URL.

What if I rename a folder manually?

airskills mv is the recommended way, but if you mv a skill folder by hand and then push, the CLI handles it. On push it spots that the renamed folder's content matches an existing skill, propagates the rename to every other agent dir that still has the old name, and tells the server. The skill keeps the same skill_id, so consumers stay attached.

You'll see a line like this:

✓ detected partial rename: old-name → new-name, propagated across all agent dirs
old-name → new-name (renamed)

Two situations this does not cover:

• Renaming and editing content in the same step. The content hash no longer matches the original, so the CLI can't tell it's a rename and treats the new folder as a brand-new skill. If you want to rename and edit, do them in two separate pushes — or use airskills mv then edit, then push.
• Renaming in folders that aren't tracked agent directories (arbitrary backups, mirrors outside ~/.claude/skills/, ~/.cursor/skills/, etc.). Airskills only manages skills inside known agent paths.

If you can use airskills mv, it's still the cleaner route — one command, atomic across every agent, no edge cases.

What if I'm not logged in?

You can still rename locally. The CLI will rename your directories across agents and update your local sync state, but it cannot tell the server. The next time you log in and push, the server-side name will catch up.

---

Deep dive: why renames don't break consumers

For curious developers — skip if you just want to use it.

A skill's identity on the server is its skill_id (a UUID), not its name or its URL. When someone runs airskills add chrismdp/code-review, the CLI:

1. Resolves the slug chrismdp/code-review to find the skill_id
2. Stores the skill_id in their local sync marker
3. From then on, fetches updates by skill_id, not by slug

When you rename code-review to pr-etiquette, the skill_id does not change. Their next pull asks the server for the same skill_id, gets the new name back as metadata, and quietly applies it. No warnings, no broken fetches, no mention.

This is also why transfer behaves differently — transfer creates a new skill_id (the old one is soft-deleted), so consumers pinned to the old skill_id see the "upstream archived" event.