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>

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.

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 four 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

You rarely type the last two. The review composes them for you — see Hand-offs.

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 says so and stops. It does not fall back to writing the plan into chat, because a plan in chat is the thing PlanX exists to replace.