feat: track skill versions in installed artifacts

README.md

@@ -92,6 +92,36 @@ Produces:
 - `dist/magicblock.full.cursor.mdc` — full Cursor rule
 - `dist/magicblock.zip` — zipped `skill/` folder for Claude.ai upload
 
+## Versioning and updates
+
+`skill/VERSION` is the single source of truth for the skill's version, starting at `0.1.0`.
+It is independent of MagicBlock SDK and protocol versions. Folder installs and ZIPs include
+`VERSION`; generated single-file artifacts include a `Skill version` comment.
+Run `./install.sh --version` to print the source checkout's version, or read `VERSION` in
+an installed skill directory.
+
+Every PR changing `skill/`, `build.sh`, or `install.sh` must increase `skill/VERSION`. Use stable `MAJOR.MINOR.PATCH` versions:
+
+- Patch for corrections and compatible packaging fixes.
+- Minor for new product coverage or compatible workflows.
+- Major for incompatible installation or workflow changes.
+
+Bump once per PR, not once per commit. README-only changes do not require a bump.
+If another version lands first, update the PR's version against the new base.
+Update `skill/VERSION` manually and run `./build.sh` to rebuild the artifacts.
+
+To update a manual installation to the latest version on `main`, start from a clean clone:
+
+```bash
+cd magicblock-dev-skill
+git switch main
+git pull --ff-only origin main
+./install.sh --codex  # reuse your original target flags
+```
+
+Installed copies do not update automatically. Review the merged PRs or Git history and rerun the installer
+when updating. Keep using the same target and project directory for project-scoped installs.
+
 ## Recommended companion skill: `solana-dev`
 
 This skill covers MagicBlock-specific patterns: ER/PER, delegation, oracles, Session Keys, cranks, VRF,

build.sh

@@ -11,6 +11,11 @@ REFERENCE_DIR="$SKILL_DIR/references"
 DIST_DIR="$SCRIPT_DIR/dist"
 SKILL_NAME="magicblock"
 REPO_URL="https://github.com/magicblock-labs/magicblock-dev-skill"
+SKILL_VERSION="$(cat "$SKILL_DIR/VERSION")"
+if [[ ! "$SKILL_VERSION" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
+    echo "Error: skill/VERSION must contain a stable MAJOR.MINOR.PATCH version" >&2
+    exit 1
+fi
 GIT_CONTEXT=false
 GIT_ROOT=""
 if command -v git >/dev/null 2>&1; then
@@ -384,6 +389,7 @@ build_flattened() {
     local ref
     {
         echo "<!-- Auto-generated $label artifact by build.sh from $REPO_URL -->"
+        echo "<!-- Skill version: $SKILL_VERSION -->"
         echo "<!-- Source commit: $SOURCE_COMMIT -->"
         echo "<!-- Source state: $SOURCE_STATE -->"
         echo "<!-- Artifact link mode: $content_mode -->"
@@ -426,6 +432,7 @@ build_system_prompt() {
         else
             echo "<!-- Self-contained prompt: exact canonical-origin publication is not locally proven -->"
         fi
+        echo "<!-- Skill version: $SKILL_VERSION -->"
         echo "<!-- Source commit: $SOURCE_COMMIT -->"
         echo "<!-- Source state: $SOURCE_STATE -->"
         echo "<!-- Artifact link mode: $LINK_MODE -->"
@@ -523,7 +530,8 @@ validate_artifacts() {
             echo "Error: unresolved relative Markdown link in $artifact" >&2
             exit 1
         fi
-        if ! grep -Fq "<!-- Source commit: $SOURCE_COMMIT -->" "$artifact" || \
+        if ! grep -Fq "<!-- Skill version: $SKILL_VERSION -->" "$artifact" || \
+           ! grep -Fq "<!-- Source commit: $SOURCE_COMMIT -->" "$artifact" || \
            ! grep -Fq "<!-- Source state: $SOURCE_STATE -->" "$artifact" || \
            ! grep -Fq "<!-- Source fingerprint: sha256:$SOURCE_FINGERPRINT -->" "$artifact"; then
             echo "Error: incomplete source provenance in $artifact" >&2

install.sh

@@ -54,6 +54,7 @@ Modifiers:
   --full         For single-file targets, preload every product reference.
                  Default single-file installs keep deep guides on demand
   --path PATH    Install the raw skill/ folder to a custom path
+  --version      Print the version in this source checkout
   -h, --help     Show this help message
 
 Defaults:
@@ -168,6 +169,8 @@ while [[ $# -gt 0 ]]; do
                 exit 1
             fi
             CUSTOM_PATH="$2"; shift 2 ;;
+        --version)
+            cat "$SOURCE_DIR/VERSION"; exit 0 ;;
         -h|--help)
             print_help; exit 0 ;;
         *)

skill/VERSION

@@ -0,0 +1 @@
+0.1.0