From 4ba53c59e38d28813b98cab2e65f1aa5393d7de1 Mon Sep 17 00:00:00 2001
From: Evan Reichard <evan@reichard.io>
Date: Thu, 28 May 2026 17:16:42 -0400
Subject: [PATCH] feat: create skill variable helper

---
 .../pi/config/skills/create-skill/SKILL.md    |  1 +
 .../skills/create-skill/assets/variable.sh    | 83 +++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100755 modules/home/programs/terminal/pi/config/skills/create-skill/assets/variable.sh

diff --git a/modules/home/programs/terminal/pi/config/skills/create-skill/SKILL.md b/modules/home/programs/terminal/pi/config/skills/create-skill/SKILL.md
index 4fbc288..0e7b5c8 100644
--- a/modules/home/programs/terminal/pi/config/skills/create-skill/SKILL.md
+++ b/modules/home/programs/terminal/pi/config/skills/create-skill/SKILL.md
@@ -45,6 +45,7 @@ description: "<One-liner: what it does and when to trigger. Keep under ~200 char
 
 - **Be concise.** Skills are injected into agent context — every line costs tokens. Aim for the minimum needed to reliably guide the agent.
 - **Use scripts for repeatable logic.** If a step involves a multi-line shell command, `jq` pipeline, or API call that won't change between runs, put it in a `.sh` file next to `SKILL.md` and reference it from the workflow. See `address-gh-review/` for an example.
+- **Needs configurable values (paths, identifiers, etc.; not secrets — values are stored as plaintext files)?** Copy `assets/variable.sh` into the new skill's `scripts/` dir as-is. It's self-contained and location-independent. Callers use `variable.sh --get NAME [--require-exec RELPATH]`; the helper prints self-explaining `--set` instructions on "unset" or "set-but-invalid" and exits non-zero, so callers just propagate. When you use it, add a `.gitignore` containing `.vars/` to the skill root — that's where the helper stores values.
 - **Frontmatter is required.** `name` and `description` fields. The description is what the agent uses to decide whether to load the skill, so make it specific about trigger conditions.
 - **Don't over-specify.** Trust the agent to fill gaps. Document the _what_ and _when_, not every micro-step.
 - **Split workflow from reference when the reference surface grows.** If a skill accumulates lookup tables, mapping rules, or capability references that the workflow consults, move them into a sibling `<skill>/<category>/` directory (e.g. `mappings/`, `references/`) with one sub-doc per category and an index `README.md`. Keep `SKILL.md` focused on the hot path — workflow, hard rules, and a short table pointing at the sub-docs. Include a brief style guide in the index README covering (a) defer to authoritative sources (stubs, schemas, generated docs) whenever possible, (b) row/entry formatting conventions, (c) when to create a new sub-doc vs. extend an existing one.
diff --git a/modules/home/programs/terminal/pi/config/skills/create-skill/assets/variable.sh b/modules/home/programs/terminal/pi/config/skills/create-skill/assets/variable.sh
new file mode 100755
index 0000000..32ac5af
--- /dev/null
+++ b/modules/home/programs/terminal/pi/config/skills/create-skill/assets/variable.sh
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Skill-local variable store. Values live in <skill-dir>/.vars/<NAME>.
+#
+# Usage:
+#   variable.sh --get NAME [--require-exec RELPATH]
+#                                  Prints value to stdout, exits 0.
+#                                  --require-exec asserts that VALUE/RELPATH
+#                                  exists and is executable; if not, prints
+#                                  the fix instructions to stderr and exits 2.
+#   variable.sh --set NAME VALUE   Writes value, exits 0.
+#
+# Callers should treat any non-zero exit as fatal; the stderr message tells
+# the caller (agent or user) exactly how to populate or correct the value.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(dirname "$SCRIPT_DIR")"
+STORE="$SKILL_DIR/.vars"
+SELF="$0"
+
+usage() {
+    cat >&2 <<EOF
+Usage:
+  $SELF --get NAME [--require-exec RELPATH]
+  $SELF --set NAME VALUE
+EOF
+    exit 2
+}
+
+op=""
+name=""
+value=""
+require_exec=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --get|--set)    op="${1#--}"; shift ;;
+        --require-exec) [[ $# -ge 2 ]] || usage; require_exec="$2"; shift 2 ;;
+        --*)            usage ;;
+        *)
+            if   [[ -z "$name"  ]]; then name="$1"
+            elif [[ -z "$value" ]]; then value="$1"
+            else usage; fi
+            shift ;;
+    esac
+done
+
+[[ -n "$op" && -n "$name" ]] || usage
+
+case "$op" in
+    get)
+        [[ -z "$value" ]] || usage
+        file="$STORE/$name"
+        if [[ ! -f "$file" ]]; then
+            cat >&2 <<EOF
+$SELF: $name is not set.
+Ask the user for the value, then set it:
+  $SELF --set $name <value>
+EOF
+            exit 2
+        fi
+        val="$(cat "$file")"
+        if [[ -n "$require_exec" && ! -x "$val/$require_exec" ]]; then
+            cat >&2 <<EOF
+$SELF: $name is set to '$val' but '$val/$require_exec' is missing or not executable.
+Update it with a valid path:
+  $SELF --set $name <new-value>
+EOF
+            exit 2
+        fi
+        printf '%s' "$val"
+        ;;
+    set)
+        [[ -n "$value" ]] || usage
+        [[ "$name" =~ ^[A-Z][A-Z0-9_]*$ ]] || {
+            echo >&2 "$SELF: invalid name '$name' (must match [A-Z][A-Z0-9_]*)"
+            exit 2
+        }
+        mkdir -p "$STORE"
+        printf '%s' "$value" > "$STORE/$name"
+        ;;
+esac