wk-env

Files (9)

• README.md
• SKILL.md
• check-skill-env-vars.sh · hooks/
• 2026-07-24_resolve-skill-dir-by-listing.md · references/
• 2026-07-24_stale-value-not-missing.md · references/
• 2026-08-11_interactive-shell-env-vars.md · references/
• 2026-10-09_input-rewrite-hook-blocks-auto.md · references/
• report-format.md · references/
• env-hook.bats · tests/

SKILL.md (first lines)

# Env

Diagnose and report environment variable availability before skill execution. Modes: **auto** — `PreToolUse` hook fires
before any `Skill` tool call and checks the target skill's `env-vars:`; **manual** — `/wk-env` (full session report),
`/wk-env <skill-name>` (that skill's vars), `/wk-env --check VAR1 VAR2` (listed vars).

## Step 1: Identify vars to check

- Skill name given → **resolve its dir by listing, never by transforming the name** (most dirs drop the leading `wk-`,
  some keep it; a blind strip reports a false "declares nothing"). Take the first candidate that exists, verbatim before
  stripped:

  ```bash
  for cand in "{name}" "${name#wk-}"; do
    f="$WK_SKILLS_HOME/skills/$cand/SKILL.md"
    [ -f "$f" ] && { SKILL_FILE="$f"; break; }
  done
  ```

  Then extract the `env-vars:` frontmatter list:

  ```bash
  awk '/^---/{n++} n==1 && /^env-vars:/{f=1;next} f && /^  -/{print $2;next} f && !/^  -/{exit}' \
    "$SKILL_FILE"
  ```

- Unresolvable name is normal input, not an error (plugin and third-party skills ship no dir here): report it as
  unresolved; never conflate it with "declares no env-vars".
- `--check VAR1 VAR2` → use those vars directly. `--all` → collect every unique var from every `skills/*/SKILL.md`
  frontmatter `env-vars:` list. No args → the default set in Step 2.

## Step 2: Check current process env

Classify each var: `set` (non-empty), `empty` (set to `""`), or `missing` (unset).

- `set` proves the var was **inherited**, never that the value is still **valid** — a rotated secret reads `set`. Route
  an auth failure on a `set` var to Step 3.5.
- **Never echo the value of a secret-shaped var** (name matching `TOKEN|KEY|SECRET|PASS|CRED|PAT`) — even a prefix
  discloses it and forces a rotation. Report those as `<len N sha XXXXXXXX>`; print the literal value only for
  non-secret vars (paths, org names).
- Distinguish unset from empty by `printenv` exit status, never `${!var+x}` (bash-only; aborts under zsh with
  `bad substitution`).

```bash
source "$HOME/.profile" 2>/dev/null || true

for var in {VARS}; do
  if ! val=$(printenv "$var"); then
    echo "missing  $var"
  elif [ -z "$val" ]; then
    echo "empty    $var"
  else
    case "$var" in
      *TOKEN*|*KEY*|*SECRET*|*PASS*|*CRED*|*PAT)
        echo "set      $var  = <len ${#val} sha $(printf %s "$val" | shasum | cut -c1-8)>" ;;
      *) echo "set      $var  = ${val:0:60}" ;;
    esac
  fi
done
```

No args → check this default set:

```bash
WK_SKILLS_HOME GITHUB_ORG EMPLOYER GIT_CONFIG_PARAMETERS
```

## Step 3: Source `$HOME/.profile` and re-check missing vars

For each `missing` or `empty` var, source `$HOME/.profile` in a diagnostic subprocess and re-check:

```bash
bash -c "source $HOME/.profile 2>/dev/null; printenv {VAR}" 2>/dev/null \
  || echo "<still missing after sourcing $HOME/.profile>"
```

Still missing → try an interactive login shell (catches interactive-only config: `[[ -o interactive ]]` blocks, plugin
managers); found → export it into the current session:

```bash
zsh -ilc "printenv {VAR}" 2>/dev/null \
  || echo "<still missing after interactive-shell probe>"
```

Report one of: **Resolved after sourcing** (var is in `$HOME/.profile` but Claude Code was not launched from a shell
that sources it); **Resolved after interactive-shell probe** (interactive-only config — export it and note the source);
**Still missing** (defined nowhere in `$HOME/.profile` or interactive config — the user needs to add it).

## Step 3.5: Diagnose a set-but-stale value

Enter only when a var reads `set` **and** the command consuming it fails auth (401 / 403 / expired token): a credential
rotated after this process started leaves a stale copy here.

- Fingerprint before and after **one** source attempt — compare length + hash prefix, never print the secret:

  ```bash
  fp() { printf '%s:%s\n' "${#1}" "$(printf %s "$1" | shasum | cut -c1-8)"; }
  fp "${{VAR}}"                                                            # in-process
  fp "$(bash -c "source \"$HOME/.profile\" 2>/dev/null; printenv {VAR}")"   # after source
  ```

- Fingerprint **changed** → the fresh value is on disk; report resolved-after-sourcing and remediate per Step 4.
- Fingerprint **unchanged** → declare the value **stale-in-process**. Stop and ask the user to restart the session, or
  to run the failing command in their own shell.
- **HARD RULE — never hunt a second shell file, and never retry the command a third time.** Sourcing a static profile
  cannot import a value minted after this process started, so every further attempt fails identically.

## Step 3.6: Diagnose a hook input-rewrite refusal

Enter when a Bash call is denied with `a hook changed this call's input after the model wrote it` (auto-mode
classifier gave no verdict). This is not a missing var: a `PreToolUse` hook on `Bash` emits
`hookSpecificOutput.updatedInput` (e.g. prepends a profile `source`), so the reviewed command differs from the one that
would run. Read-only calls skip the classifier → only writes (push, POST, merge) fail.

- Name the hook — read it, never guess:

  ```bash
  command grep -n 'updatedInput' "$HOME/.claude/settings.json"
  ```

From whizzzkid/skills, MIT.

More from whizzzkid/skills