The Skill

The skill

PlanX ships a skill rather than a prompt to paste. A skill is a file the agent already knows how to find: it carries a name, a description and an argument hint, and the agent loads its instructions when you invoke it. Nothing has to be kept in a snippets file, and nothing drifts out of date with the CLI — an upgrade rewrites the skill, so the instructions the agent reads always match the planx on your PATH.

Invoking it

Agent	Type
Claude Code	/planx <task>
Codex	$planx <task>
Another agent	The skill invocation syntax that agent supports

That difference is real, not cosmetic: it is how each agent spells a skill invocation, and PlanX uses the right one when it composes a command for you. The skill itself is not limited to those two agents. Install it in another skill-capable agent and add that agent as a custom command.

A new agent session is required after installing. A session already running loaded its skills at start-up and does not see one written underneath it.

The five branches

The skill dispatches on what follows the invocation, and reads only the reference file for the branch it took.

You typed	The agent does
/planx alone	Says it is ready, and asks what to plan
/planx <task>	Plans it: clarify, research, write, capture, stop
/planx revise <id> v<n>	Reads the review and captures the next version
/planx execute <id> v<n>	Marks the version being built, and builds it
/planx help <question>	Answers it from this wiki, in chat

You rarely type revise or execute. The review composes them for you — see Hand-offs.

help is a question about PlanX itself. A task that starts with the word help — /planx help me split the auth module — is planned like any other; see Asking for help.

The version travels with the command

revise and execute both arrive as <id> v<n>, and that is the version you reviewed. The skill passes it through unchanged and never substitutes latest, because a plan can gain a version between your review and the command running. An agent that defaulted to latest would build a plan nobody has read.

latest still resolves — it just has to be said out loud.

Rules that hold on every branch

Three, and they apply while planning, revising and executing alike.

~/.planx is never edited by the agent. Every change goes through the CLI.

One capture per revision. Capturing text identical to the current latest is a safe no-op that hands back the existing version, so a skill may call it defensively. Two captures of two different texts are two versions, and you now have a review round to spend working out which one you are reading.

A follow-up message is one of three things — a change to the plan on the table, a different piece of work, or an instruction to build it. The agent decides which, and asks when it is not obvious. It never silently starts a second plan and never silently starts implementing.

If planx is not installed

The skill never falls back to writing the plan into chat, because a plan in chat is the thing PlanX exists to replace. Instead it says the CLI is missing and offers to install it — npm install --global @thisisnsh/planx. Agree and it runs the install, checks that planx --version answers, and carries on with the branch you were on. Decline, or let the install fail, and it stops and leaves you the command.

That matters because the skill travels on its own. Skill directories redistribute SKILL.md files, npx skills add installs the skill without the package, and a plugin install does the same — so copies exist that never came through npm. The install repairs the copy that triggered it: postinstall runs planx add-skills, which overwrites the skill in place with the version matching the CLI. One /planx in a broken install ends with a working install and the plan you asked for. See Installation.