fix(engine): write skills/sub-agents to ${HOME}/.claude regardless of CLAUDE_CONFIG_DIR

setup-claude.sh writes per-pod settings.json, MCP config, custom
skills, and sub-agents into either ${CLAUDE_CONFIG_DIR}/ (when set
for session persistence) or ${HOME}/.claude/ (when not). Claude Code
respects CLAUDE_CONFIG_DIR for the first two, but its slash-command
skill and sub-agent discovery is hardcoded to read from the
HOME-relative paths ${HOME}/.claude/skills/ and
${HOME}/.claude/agents/, irrespective of CLAUDE_CONFIG_DIR. The
result on session-persistence-enabled deployments: skills were
correctly delivered into the pod's PVC mount but invisible to the
agent — invocations failed with "Unknown skill: <name>".

The fix moves both directories under ${HOME}/.claude/ unconditionally.
Skills and sub-agents are deterministically regenerated from the
CLAUDE_SKILL_* and CLAUDE_SUBAGENT_PATH_* env vars at every pod start
— the env vars are set by the controller per Job, so a restart
rebuilds them identically. They don't benefit from PVC persistence
the way the session JSONLs do, so the previous co-location of all
config under ${CLAUDE_DIR} was incidental rather than intentional.

settings.json, the MCP config, and CLAUDE_CONFIG_DIR's export are
unchanged — those genuinely live under whichever directory the
operator pointed at, and Claude Code reads them from there.

Behaviour change: skill/sub-agent files no longer take PVC space on
deployments that enable session persistence. Operators who relied on
in-place edits surviving pod restarts (an unintended emergent
property of the previous layout) will see those edits regenerated
from env vars. Anyone authoring skills should be doing so via the
controller's config (inline or ConfigMap-backed) rather than editing
the file inside the running pod, so this is closer to the documented
contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sarahjanenewnham

CHANGELOG.md

@@ -28,6 +28,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Skill and sub-agent discovery under session persistence**:
+  `setup-claude.sh` previously wrote `CLAUDE_SKILL_*` and
+  `CLAUDE_SUBAGENT_PATH_*` files to `${CLAUDE_CONFIG_DIR:-${HOME}/.claude}/skills/`
+  and `${CLAUDE_CONFIG_DIR:-${HOME}/.claude}/agents/`. When session
+  persistence was enabled (`CLAUDE_CONFIG_DIR` set to a PVC-backed
+  path), the files landed there but were invisible to Claude Code,
+  whose slash-command discovery reads from the HOME-relative paths
+  `${HOME}/.claude/skills/` and `${HOME}/.claude/agents/` regardless
+  of `CLAUDE_CONFIG_DIR`. The agent then surfaced the file as
+  "Unknown skill: <name>" on `/skill-name` invocations. The script
+  now writes both directories under `${HOME}/.claude/` always —
+  these files are deterministically regenerated from the env vars at
+  every pod start, so they don't need PVC persistence the way
+  session JSONL files do.
 - **Review poller acting on bot summary comments**: the classifier now only
   ignores bot comments that lack a file position (summaries, coverage reports).
   Inline diff comments from bots (e.g. CodeRabbit review suggestions) are still

docker/engine-claude-code/setup-claude.sh

@@ -50,34 +50,50 @@ cp /etc/claude-code/mcp.json /workspace/.mcp.json
 # path is in use.  A no-op when CLAUDE_CONFIG_DIR was already set in the env.
 export CLAUDE_CONFIG_DIR="${CLAUDE_DIR}"
 
-# Write custom skill files if any skill env vars are present.
+# Write custom skill files if any skill env vars are present. Skills go
+# to ${HOME}/.claude/skills/ — not ${CLAUDE_DIR}/skills/ — because
+# Claude Code's slash-command discovery reads from the HOME-relative
+# path regardless of CLAUDE_CONFIG_DIR. Writing to ${CLAUDE_DIR}/skills/
+# under session persistence (CLAUDE_CONFIG_DIR set) leaves the file on
+# the PVC but invisible to the agent: invocations fail with "Unknown
+# skill: <name>". Skills are deterministically regenerated from the
+# CLAUDE_SKILL_* env vars at every pod start, so they don't need PVC
+# persistence the way session JSONL files do.
+#
 # Inline skills: CLAUDE_SKILL_INLINE_<NAME>=<base64-encoded Markdown>
 # Path skills:   CLAUDE_SKILL_PATH_<NAME>=<path on image>
 if env | grep -q '^CLAUDE_SKILL_'; then
-    mkdir -p "${CLAUDE_DIR}/skills"
+    SKILLS_DIR="${HOME}/.claude/skills"
+    mkdir -p "${SKILLS_DIR}"
 
     # Write inline skills (base64-decoded content).
     for var in $(env | grep '^CLAUDE_SKILL_INLINE_' | sed 's/=.*//'); do
         name=$(printf '%s' "$var" | sed 's/^CLAUDE_SKILL_INLINE_//' | tr '[:upper:]' '[:lower:]' | tr '_' '-')
-        printenv "$var" | base64 -d > "${CLAUDE_DIR}/skills/${name}.md"
+        printenv "$var" | base64 -d > "${SKILLS_DIR}/${name}.md"
     done
 
     # Copy path-based skills from the image.
     for var in $(env | grep '^CLAUDE_SKILL_PATH_' | sed 's/=.*//'); do
         name=$(printf '%s' "$var" | sed 's/^CLAUDE_SKILL_PATH_//' | tr '[:upper:]' '[:lower:]' | tr '_' '-')
         path=$(printenv "$var")
-        [ -f "$path" ] && cp "$path" "${CLAUDE_DIR}/skills/${name}.md"
+        [ -f "$path" ] && cp "$path" "${SKILLS_DIR}/${name}.md"
     done
 fi
 
-# Write ConfigMap-backed sub-agent files to ~/.claude/agents/.
+# Write ConfigMap-backed sub-agent files to ${HOME}/.claude/agents/.
+# Same HOME-relative reasoning as skills above: Claude Code's sub-agent
+# discovery uses the HOME-relative path regardless of CLAUDE_CONFIG_DIR,
+# so writing under ${CLAUDE_DIR} when session persistence is on would
+# make the sub-agent invisible to the agent.
+#
 # Sub-agent env vars: CLAUDE_SUBAGENT_PATH_<NAME>=<path on volume>
 if env | grep -q '^CLAUDE_SUBAGENT_PATH_'; then
-    mkdir -p "${CLAUDE_DIR}/agents"
+    AGENTS_DIR="${HOME}/.claude/agents"
+    mkdir -p "${AGENTS_DIR}"
     for var in $(env | grep '^CLAUDE_SUBAGENT_PATH_' | sed 's/=.*//'); do
         name=$(printf '%s' "$var" | sed 's/^CLAUDE_SUBAGENT_PATH_//' | tr '[:upper:]' '[:lower:]' | tr '_' '-')
         path=$(printenv "$var")
-        [ -f "$path" ] && cp "$path" "${CLAUDE_DIR}/agents/${name}.md"
+        [ -f "$path" ] && cp "$path" "${AGENTS_DIR}/${name}.md"
     done
 fi