A short name for a frequently used skill: /pk runs peek exactly as /peek does.
How to add an alias, how the deploy builds it, and why it is a plain copy of its skill. Model file and frontmatter: Skill model.
Add an aliases line to the skill's frontmatter in <leaf>.cue; comma-separate several.
aliases: pk
Bump the version, render and sync as usual. Each alias becomes a full skill under ~/.claude/skills/<alias>/ and ~/.codex/skills/<alias>/.
If the allow list of settings/claude_code/components/gate.json has a Skill(<name>) line for the skill, add Skill(<alias>) beside it by hand. A typed /<alias> works without it; the line lets an agent call the alias.
The skills sync writes each alias as a copy of its skill's deployed dir. The repo keeps one source, the canonical <leaf>.cue; alias copies exist only in the deployed homes.
| Aspect | Behaviour |
|---|---|
| The copy | Only SKILL.md differs: name is the alias, and a skill without title-code gets its own name as title-code, so session titles match under both names. The body is unchanged and still names the skill. |
| Model check | Rejects an alias that is not kebab-case, repeats the skill's name, or appears twice. |
| Pruning | Alias dirs count as repo skills: pruning keeps them, the casual-profile skill overrides list them. An alias removed from <leaf>.cue goes to the trash at the next pruning sync: the install engine's, the config server's, and configserver -sync-skills only with -sync-prune. |
| Config server | Treats an alias as its skill: no own card, a badge on the skill's row and detail page, invocations counted with the skill's. Its session-report rows show the skill's version and tokens. |
| Usage store | Keeps the name as typed. |
Two skills claiming the same alias, or an alias shadowing another skill's name: the later deploy overwrites the earlier dir.
Each alias costs one extra description in the skill listing; every alternative was more fragile.
| Alternative | Why not |
|---|---|
| A native alias or a hook redirect | Claude Code has no alias feature. Hooks can block a prompt or add context, not rewrite what runs. |
| Renaming the deployed directory | A directory name also invokes the skill, but allows only one alias and breaks the canonical name: every hook finds a skill by the name typed (tool grants, context injection, --help, session titles). |
| A symlink per alias | Undocumented behaviour: Claude Code loads a symlinked skill only once, and which name survives is unspecified. The prune skips a symlinked skill dir. A deploy under its name that finds it unmarked or modified trashes the link itself, never its target, and writes a plain dir. |
| A stub skill that forwards | A tool round-trip per call and a second skill run for hooks to track. |
A plain copy is a real skill at a real path: every hook that finds a skill by the name typed works unchanged. The global Skill(<name>) grant is the one list that needs the alias added.