Versioned Prompts

You don't need to do this by hand

This page explains how things work under the hood. In normal use, your AI sessions run these skit commands for you; see skit → As a user.

In IST, the instructions an AI session follows are not text you paste into a chat. They are files shipped in a kit, installed with skit, and versioned like any other package.

This page explains why.

Prompts are what you ship

A Manager/Worker setup works because every session gets the same instructions: how to delegate, how to report, which tools to call. Those instructions are as much a part of the system as the CLIs themselves. If they drift, behavior drifts.

So IST treats them as a release artifact:

Kit part	What it is	Where it ends up
Profile	The system prompt and allowed tools for one role (e.g. tda-worker)	~/.ist/profiles/
Prompt	An on-demand instruction a session reads with skit prompt show <name>	~/.ist/prompts/global/ or ~/.ist/prompts/profiles/<profile>/
CLI dependencies	The commands the prompts tell the AI to run	Global npm packages
Hooks, states, permission packs	Supporting files	See Installation Locations

A kit has a name and a version (@ist/tda-kit@<version>), and skit install records which version of which kit wrote which files in ~/.ist/installed-kits.json.

What versioning gives you

Reproducibility

Two machines that install the same kit version get the same profile and prompt files. A kit also pins the CLI versions its prompts were written against, so a prompt never tells the AI to use a flag the installed CLI does not have.

An IST release goes one step further: snapshot install @ist/beta installs a tested combination of CLIs and kits at fixed versions. Run snapshot current to see what you have.

Clean upgrades and rollback

Re-installing a kit removes the files recorded for its previous version before copying the new ones. A prompt that was dropped in the new version disappears instead of lingering.

Because any published version can be installed again, rolling back is an ordinary install:

skit install @ist/tda-kit@<previous-version>

You can check what is installed at any time:

skit list
skit prompt list

Ownership is explicit

skit knows which files belong to which kit. Anything under ~/.ist/prompts/ or ~/.ist/profiles/ that no kit owns shows up in skit orphans, which makes hand edits visible instead of silent.

Slots: where your own instructions go

Kits are shared; your project's rules are not. Kit authors therefore leave slots: a profile tells the AI to read a prompt that the kit does not ship, and you provide it.

The TDA profiles use a conventions slot. On startup, a tda-worker session is told to run:

skit prompt show conventions --profile tda-worker 2>/dev/null \
  || skit prompt show conventions

and to continue without it if neither exists. To fill the slot, write the file yourself:

File	Read by
~/.ist/prompts/profiles/tda-worker/conventions.md	tda-worker sessions only
~/.ist/prompts/global/conventions.md	Every role that looks for conventions

Because no kit owns these files:

• Upgrading or reinstalling the kit does not touch them. Your conventions survive kit updates.
• skit orphans lists them. That is expected. Don't run skit orphans --clean without checking the list.

The general rule: put shared, versioned behavior in kits, and put local, project-specific rules in slots.

Next

• What Changes on an Upgrade: what moves together when a kit or an IST release is upgraded
• When Sessions Load Prompts: when a session actually sees the new files