Versioning

Skills in ContextPie are immutable. You never edit a skill in place — saving creates a new version. Old versions and their files are never mutated. This keeps history honest and makes analytics attributable.

How versions work

Each save produces the next version (v1, v2, v3…). Exactly one version is marked current, and that's the only one agents ever read via get_skill. The rest stay frozen and browsable.

v1  ──save──▶  v2  ──save──▶  v3   ◀── current (served to agents)
(frozen)       (frozen)       (live)

• Saving creates a new version. Edits to the body, description, trigger phrases, or supporting files all roll into a new version.
• Old versions are immutable. Their bodies, files, and embeddings never change.
• One version is current. Agents always read the current version; promoting a different version is how you "publish" a change.
• History is browsable. You can inspect any past version in the editor.

Tags: moving pointers for environments

A tag is a named, movable pointer to one version — think prod, dev, or staging. It works like a LangSmith prompt-hub tag or a git branch: the tag names a version, and re-tagging moves it. A tag lives on exactly one version at a time, so pointing prod at v5 detaches it from v3 — "what is prod?" is never ambiguous.

Tags are how you deploy across environments. Tag one version dev and another prod; each environment connects with its tag and fetches the version that tag points at, while you keep authoring new versions without disturbing what prod serves.

• Set the tag on the connection, not per call — add ?tag=prod to your MCP endpoint (…/w/your-workspace?tag=prod). It applies to the whole connection; see Connecting an agent.
• Retrieval: on a tagged connection, every tool resolves to that tag's version — find_skills only surfaces skills that carry the tag (and ranks on the tagged version), and get_skill / get_skill_file serve it. With no tag, a connection gets each skill's current (latest) version.
• Tagging never creates a version. Tags are mutable pointers over immutable versions — moving prod doesn't edit anything.
• Any name you like, lowercase (letters, numbers, ., _, -), as long as it isn't only digits (so it can't be confused with a version number).

Set tags from the editor: open the Tags menu on the version you're viewing to add a new tag or move an existing one onto it. The Versions panel shows each version's tags, so you can see at a glance what prod and dev point at.

Why immutability matters

Reproducibility: a skill version is a fixed artifact. If an agent behaved a certain way last Tuesday, you can see the exact body and files it read.

Immutability also makes telemetry attribution clean. Every search, load, and file_load event in Analytics ties to a specific version. Without that, you couldn't tell whether a skill went "dead" because it's genuinely unused or because you rewrote it yesterday. Versioning separates "nobody wants this" from "this just changed."

When you improve discoverability by sharpening a description or trigger phrases, the new version's embedding is recomputed on save — the old version's stays untouched.