promptalias

The visual walkthrough is at kishormorol.github.io/promptalias — what a prompt is, the seven of them, how a typed sentence reaches one, and what is actually measured.

Reusable prompts, written once as Agent Skills and shared across Claude Code, Codex, and Cursor. Each prompt is a folder with a SKILL.md, and npx skills distributes them to every agent's skills directory.

There is no promptalias command. The name comes from a CLI that was designed and then killed before implementation — a compiler from one terse YAML file into per-tool command files. It turned out the three tools had converged on a single format, so there was nothing left to compile. The name stuck; the compiler never happened. The full reasoning, with links, is in docs/prior-art.md.

This is not a text expander and not a config-sync tool. Espanso expands triggers into text system-wide in any app, and knows nothing about agent command formats. rulesync, vsync, and agent-skill-porter compile or convert configs between tools' directories. This repo skips that whole category: the three tools already read the same SKILL.md format, so there is nothing to compile. See docs/prior-art.md for the research that led here, including the two research passes that killed the CLI.

Install

npx skills add . --global --all   # install every skill for every agent
npx skills list -g                # show what's installed where

Two caveats worth knowing, both measured rather than assumed.

add copies; it does not link back here. It writes each SKILL.md into a hub at ~/.agents/skills/<name>/ and symlinks agent directories at the hub. Edits to this repo are therefore invisible until you re-run add. Confirmed by editing update-feature/SKILL.md and watching the hub not change.

add did not reach Codex or Cursor. It reported success for both while writing only to the hub, leaving ~/.codex/skills/ empty and ~/.cursor/skills-cursor/ untouched.

The fix for both is one chain of symlinks — point the hub at this repo, then point each tool at the hub:

mkdir -p ~/.agents/skills ~/.claude/skills ~/.codex/skills ~/.cursor/skills-cursor
for s in update-feature build-new review-diff write-tests debug-failure explain-code plan-approach; do
  rm -rf ~/.agents/skills/$s
  ln -s  ~/promptalias/$s          ~/.agents/skills/$s
  ln -sfn ../../.agents/skills/$s  ~/.claude/skills/$s
  ln -sfn ~/.agents/skills/$s      ~/.codex/skills/$s
  ln -sfn ~/.agents/skills/$s      ~/.cursor/skills-cursor/$s
done

Re-run it after adding a prompt — a new folder is not linked until you do. The ~/.claude/skills line matters: add created that entry for the first two prompts and nothing recreates it for later ones, so a new prompt reaches Codex and Cursor while staying invisible to Claude Code. Measured on this machine, by hitting exactly that.

Current state on this machine

All three resolve to this repo, and edits are live with no sync step:

Tool	Path	Resolves to
Claude Code	~/.claude/skills/update-feature	~/promptalias/update-feature ✅
Codex	~/.codex/skills/update-feature	~/promptalias/update-feature ✅
Cursor	~/.cursor/skills-cursor/update-feature	~/promptalias/update-feature ✅

The tradeoff: npx skills no longer manages these entries, so a future add or update may replace the links with copies again. If /update-feature stops picking up your edits, that's what happened — re-run the block above.

On another machine

Now that this repo is public, install from GitHub instead of a local path:

npx skills add kishormorol/promptalias --global --all

That also sets Source: to the repo rather than local, which is what makes npx skills update able to pull anything.

Prompts

Trigger	Does
/build-new	Build something new that isn't there yet, with tests
/update-feature	Update an existing feature, keeping its tests green
/write-tests	Write tests for code that already works
/debug-failure	Track a failure to its root cause and fix it
/review-diff	Review the last diff for correctness, security, and performance
/explain-code	Explain existing code, changing nothing
/plan-approach	Plan an approach before any code is written

/build-new and /update-feature split on whether the thing exists yet; /explain-code and /plan-approach are the two that write no code at all.

The folder name is the trigger: update-feature/ gives you /update-feature. Until 10 November 2026 these were one- and two-letter names (/u, /n, /t, /d, /rv, /ex, /p). They were renamed because a letter does not say what it does, and because a name as short as /p or /d is one another tool is likely to want.

Adding a prompt

mkdir mytrigger && $EDITOR mytrigger/SKILL.md

---
name: mytrigger
description: Do X. Use when the user asks to …
---

Body of the prompt. $ARGUMENTS interpolates whatever followed the trigger.

One rule that matters more than the rest: write description as "do X. Use when Y." The Use when clause is what the agent matches on to fire the skill implicitly. A bare label like "Update a feature" will never auto-invoke — it only works if you type /update-feature yourself. How well the clause actually carries is measured in docs/auto-invocation.md.

This is the beginning of the README. Read the rest at the original. Read the full README ↗