feat(deploy): rewrite deploy-skill.sh for ai-skills module workflow

- Script now shows what to add to skill lists (no file copying)
- Supports --pi-only flag for extension-dependent skills
- Checks skills.nix registry
- Update work doc with completed phases

Also filed issue for direnv cleanup (skills-vpdp)

.beads/issues.jsonl

@@ -293,6 +293,7 @@
 {"id":"skills-vdup","title":"worker CLI: Retry limits and escalation policy","description":"From orch architecture review.\n\nProblem: Agent can enter \"loop of death\" - repeatedly spawning workers that fail.\n\nNeed:\n- Max retries per task before escalation\n- Escalation path (to human? to different agent?)\n- \"Circuit breaker\" pattern at orchestration level\n- Configurable per-task or global limits\n\nRelated: \n- skills-1jc (stuck agent detection)\n- review-gate circuit breaker (exists, 3 attempts)\n\nHQ skill should include: \"If task fails N times, escalate to human\"","status":"open","priority":2,"issue_type":"task","created_at":"2026-01-11T21:12:44.745049544-08:00","created_by":"dan","updated_at":"2026-01-12T10:06:39.334711025-08:00","dependencies":[{"issue_id":"skills-vdup","depends_on_id":"skills-s6y","type":"blocks","created_at":"2026-01-11T21:13:02.95738684-08:00","created_by":"dan"}],"comments":[{"id":4,"issue_id":"skills-vdup","author":"dan","text":"[HQ:merge:2026-01-12T09:36:22-08:00] Merged feedback from skills-gyvt (orch consensus):\n\nPROBLEM (flash-or, gemini, gpt):\nHQ is stateless between sessions. '3 failures then escalate' won't work unless retry count explicitly tracked. Could burn $50 in API credits if HQ/worker loop.\n\nSUGGESTIONS:\n1. worker status returns retry_count\n2. worker request-changes auto-increments counter in state\n3. Global token/cost budget per task ID\n4. Failure categories with different remedies\n5. Hard stop for human intervention regardless of count\n\nOWNER: worker CLI (state machine), not HQ","created_at":"2026-01-12T17:36:22Z"},{"id":13,"issue_id":"skills-vdup","author":"dan","text":"[RECLASSIFY:2026-01-12T10:06:39-08:00] Moved to worker CLI layer. Retry counting is part of worker state machine.","created_at":"2026-01-12T18:06:39Z"}]}
 {"id":"skills-vex7","title":"Design test-review skill","status":"closed","priority":2,"issue_type":"task","owner":"dan@delpad","created_at":"2026-01-19T12:43:42.726113751-08:00","created_by":"dan","updated_at":"2026-01-19T14:40:56.382537754-08:00","closed_at":"2026-01-19T14:40:56.382537754-08:00","close_reason":"Closed"}
 {"id":"skills-vjm","title":"Refactor update-agent-context.sh: reduce nesting depth","description":"File: .specify/scripts/bash/update-agent-context.sh\n\nIssues:\n- update_existing_agent_file() has 4-level deep nesting (lines 360-499)\n- State machine with multiple variables: in_tech_section, in_changes_section, tech_entries_added\n- 70+ lines of while loop processing\n\nFix:\n- Extract file processing to separate function\n- Consider sed/awk for line-based transformations\n- Use guard clauses to reduce nesting\n\nSeverity: HIGH","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-24T02:50:57.874439288-05:00","updated_at":"2025-12-25T01:44:58.38265672-05:00","closed_at":"2025-12-25T01:44:58.38265672-05:00","close_reason":"update-agent-context.sh is .specify upstream code, not maintained here"}
+{"id":"skills-vpdp","title":"Audit and clean up direnv usage across proj/ directories","description":"## Context\nMany proj/ directories have .envrc files with `use flake` that add direnv load time. Some may no longer be needed if dependencies are available globally.\n\n## Current State\nFound ~20 .envrc files in ~/proj/*/\n\nTypical content:\n```\nuse flake\nuse_api_keys\n```\n\n## Questions to Answer\n1. Which devshells provide tools not available globally?\n2. Which repos actually need isolated dev environments?\n3. Can `use_api_keys` be handled differently (e.g., global shell config)?\n\n## Potential Actions\n- Remove .envrc from repos that don't need devshells\n- Consolidate common tools to global config\n- Keep .envrc only for repos with specific toolchain needs (e.g., specific node/python versions)","status":"open","priority":3,"issue_type":"task","owner":"dan@delpad","created_at":"2026-01-25T12:30:50.915569625-08:00","created_by":"dan","updated_at":"2026-01-25T12:30:50.915569625-08:00"}
 {"id":"skills-vpy","title":"Design checklist support for skills","description":"Design how checklists fit into the skills system.\n\nQuestions:\n- Skill-as-checklist (SKILL.md with just items, no scripts)?\n- Separate checklist format?\n- Trigger conditions in frontmatter?\n- Integration with bd audit for tracking?\n\nTiers considered:\n1. AGENTS.md (simplest, no tracking)\n2. Skill-as-checklist (deployed, invokable)\n3. Proto (full tracking, overhead)","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-23T17:59:09.569427412-05:00","updated_at":"2025-12-29T13:55:35.848981398-05:00","closed_at":"2025-12-29T13:55:35.848981398-05:00","close_reason":"Parked with ADR-001: skills-molecules integration deferred. Current simpler approach (skills as standalone) works well. Revisit when complex orchestration needed."}
 {"id":"skills-vqm8","title":"TEST: Ambiguity Trap - BlueShield","status":"open","priority":2,"issue_type":"task","owner":"dan@delpad","created_at":"2026-01-12T22:09:45.95727006-08:00","created_by":"dan","updated_at":"2026-01-12T22:09:45.95727006-08:00"}
 {"id":"skills-vuj2","title":"Add validateTaskId() at CLI entry points","description":"[SECURITY] MED worker.nim - taskId from CLI args used without validation. Add validateTaskId() check in each command. Related to skills-73yu (git.nim validation).","status":"closed","priority":2,"issue_type":"bug","created_at":"2026-01-10T20:12:10.919427534-08:00","created_by":"dan","updated_at":"2026-01-10T20:32:28.382482296-08:00","closed_at":"2026-01-10T20:32:28.382482296-08:00","close_reason":"Created utils.nim with common helpers"}

bin/deploy-skill.sh

@@ -1,35 +1,34 @@
 #!/usr/bin/env bash
-# Deploy a skill from this repo to dotfiles for system-wide availability
+# Deploy a skill from this repo to the ai-skills module skill lists
 
 set -euo pipefail
 
 SKILLS_REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 DOTFILES_REPO="$HOME/proj/dotfiles"
-SKILL_NAME="${1:-}"
+SKILL_NAME=""
+PI_ONLY=false
 
 usage() {
     cat <<EOF
-Usage: $0 <skill-name>
+Usage: $0 [--pi-only] <skill-name>
 
-Deploy a skill from ~/proj/skills to ~/proj/dotfiles for system-wide deployment.
+Add a skill to the ai-skills module deployment lists.
 
 Arguments:
     skill-name    Name of skill directory in skills/
+    --pi-only     Deploy only to pi (for extension-dependent skills)
 
 Examples:
-    $0 screenshot-latest
+    $0 web-search           # Deploy to all agents
-    $0 niri-window-capture
+    $0 --pi-only ralph-work-loop  # Deploy to pi only
 
 This script:
-1. Copies skill to dotfiles/claude/skills/
+1. Validates the skill exists in skills/
-2. Shows you the Nix config to add
+2. Checks if skill is in skills.nix registry
-3. Reminds you to rebuild
+3. Shows which agent lists to update in dotfiles/home/claude.nix
 
-You must manually:
+Skills are sourced from this repo via Nix flake.
-- Edit home/claude.nix
+The ai-skills module deploys them to agent locations.
-- Edit home/opencode.nix  
-- Run: sudo nixos-rebuild switch --flake .#delpad
-- Restart AI agents
 
 Available skills:
 EOF
@@ -37,88 +36,28 @@ EOF
     exit 1
 }
 
-# Function to inject config into Nix file
+# Parse arguments
-inject_nix_config() {
+while [[ $# -gt 0 ]]; do
-    local target_file="$1"
+    case $1 in
-    local config_block="$2"
+        --pi-only)
-    local marker="$3" # Unique string to check if already deployed
+            PI_ONLY=true
-
+            shift
-    if [[ ! -f "$target_file" ]]; then
+            ;;
-        echo "⚠️  File not found: $target_file (skipping)"
+        --help|-h)
-        return
+            usage
-    fi
+            ;;
-
+        *)
-    if grep -q "$marker" "$target_file"; then
+            SKILL_NAME="$1"
-        echo "ℹ️  Config already present in $(basename "$target_file")"
+            shift
-    else
+            ;;
-        echo "Injecting config into $(basename "$target_file")..."
+    esac
-        
+done
-        # Create a secure temporary file
-        local temp_file
-        temp_file=$(mktemp "${target_file}.XXXXXX")
-        # Ensure cleanup on exit or error
-        trap 'rm -f "$temp_file"' EXIT
-        
-        # Insert before the last line (assuming it is '}')
-        if ! head -n -1 "$target_file" > "$temp_file"; then
-            echo "Error: failed to read $target_file" >&2
-            return 1
-        fi
-        
-        echo "$config_block" >> "$temp_file"
-        
-        if ! tail -n 1 "$target_file" >> "$temp_file"; then
-            echo "Error: failed to append to $temp_file" >&2
-            return 1
-        fi
-
-        # Validate: temp file should be larger than original (since we're adding)
-        local orig_size
-        orig_size=$(stat -c%s "$target_file")
-        local new_size
-        new_size=$(stat -c%s "$temp_file")
-        
-        if [[ $new_size -le $orig_size ]]; then
-            echo "Error: Validation failed, new file is not larger than original" >&2
-            return 1
-        fi
-
-        # Atomic move
-        if ! mv "$temp_file" "$target_file"; then
-            echo "Error: Failed to replace $target_file" >&2
-            return 1
-        fi
-        
-        # Clear trap after successful move
-        trap - EXIT
-        echo "✓ Updated $(basename "$target_file")"
-    fi
-}
-
-# Helper to inject a home.file entry into a Nix config
-# Usage: inject_home_file <target_nix_file> <dest_path_in_home> <source_relative_to_config> <extra_props> <comment>
-inject_home_file() {
-    local target_file="$1"
-    local home_path="$2"
-    local source_path="$3"
-    local extra_props="$4"
-    local comment="$5"
-
-    local config_block="
-  # Skill: $comment
-  home.file.\"$home_path\" = {
-    source = $source_path;
-    $extra_props
-  };"
-    inject_nix_config "$target_file" "$config_block" "$home_path"
-}
 
 if [[ -z "$SKILL_NAME" ]]; then
     usage
 fi
 
 SKILL_SOURCE="$SKILLS_REPO/skills/$SKILL_NAME"
-SKILL_DEST="$DOTFILES_REPO/claude/skills/$SKILL_NAME"
 
 # Validate skill exists
 if [[ ! -d "$SKILL_SOURCE" ]]; then
@@ -127,128 +66,64 @@ if [[ ! -d "$SKILL_SOURCE" ]]; then
     usage
 fi
 
-# Validate dotfiles repo exists
-if [[ ! -d "$DOTFILES_REPO" ]]; then
-    echo "Error: Dotfiles repo not found: $DOTFILES_REPO" >&2
-    exit 1
-fi
-
 # Check if skill has SKILL.md
 if [[ ! -f "$SKILL_SOURCE/SKILL.md" ]]; then
     echo "Error: $SKILL_NAME missing SKILL.md" >&2
     exit 1
 fi
 
-# Check if already deployed
+# Check if in skills.nix registry
-if [[ -d "$SKILL_DEST" ]]; then
+if ! grep -q "\"$SKILL_NAME\"" "$SKILLS_REPO/skills.nix" 2>/dev/null && \
-    echo "⚠️  Skill already deployed: $SKILL_DEST"
+   ! grep -q "^  $SKILL_NAME = " "$SKILLS_REPO/skills.nix" 2>/dev/null; then
-    read -p "Overwrite? [y/N] " -n 1 -r
+    echo "⚠️  Skill '$SKILL_NAME' not in skills.nix registry"
-    echo
+    echo ""
-    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    echo "Add to skills.nix:"
-        echo "Cancelled"
+    echo "  $SKILL_NAME = \"<description>\";"
+    echo ""
+fi
+
+# Check current deployment status
+CLAUDE_NIX="$DOTFILES_REPO/home/claude.nix"
+if [[ ! -f "$CLAUDE_NIX" ]]; then
+    echo "Error: $CLAUDE_NIX not found" >&2
     exit 1
-    fi
-    rm -rf "$SKILL_DEST"
 fi
 
-# Check for security docs
+echo "Skill: $SKILL_NAME"
-SECURITY_WARNING=""
-if [[ -f "$SKILL_SOURCE/SECURITY.md" ]]; then
-    SECURITY_WARNING="
-⚠️  ⚠️  ⚠️  SECURITY WARNING ⚠️  ⚠️  ⚠️
-
-This skill has security documentation.
-READ BEFORE DEPLOYING: $SKILL_DEST/SECURITY.md
-
-Security-sensitive skills should only be deployed after:
-1. Reviewing security documentation
-2. Understanding risks and mitigations
-3. Configuring protection mechanisms
-"
-fi
-
-echo "Deploying skill: $SKILL_NAME"
-echo ""
 echo "Source: $SKILL_SOURCE"
-echo "Dest:   $SKILL_DEST"
 echo ""
 
-# Copy skill
+# Check if already deployed
-mkdir -p "$(dirname "$SKILL_DEST")"
+in_claude=$(grep -c "\"$SKILL_NAME\"" "$CLAUDE_NIX" 2>/dev/null | grep -v "^0$" || true)
-cp -r "$SKILL_SOURCE" "$SKILL_DEST"
 
-echo "✓ Skill copied to dotfiles"
+if [[ -n "$in_claude" ]]; then
-echo ""
+    echo "✓ Already in deployment lists"
-
+    echo ""
-if [[ -n "$SECURITY_WARNING" ]]; then
+    echo "Current deployment:"
-    echo "$SECURITY_WARNING"
+    grep -B2 -A2 "\"$SKILL_NAME\"" "$CLAUDE_NIX" | head -20
-fi
-
-echo "Configuring system..."
-echo ""
-
-# 1. Claude Code Config
-inject_home_file "$DOTFILES_REPO/home/claude.nix" \
-    ".claude/skills/$SKILL_NAME" \
-    "../claude/skills/$SKILL_NAME" \
-    "recursive = true;" \
-    "$SKILL_NAME"
-
-# 2. OpenCode Config
-inject_home_file "$DOTFILES_REPO/home/opencode.nix" \
-    ".config/opencode/skills/$SKILL_NAME" \
-    "../claude/skills/$SKILL_NAME" \
-    "recursive = true;" \
-    "$SKILL_NAME"
-
-# 3. Codex Config (if home/codex.nix exists)
-if [[ -f "$DOTFILES_REPO/home/codex.nix" ]]; then
-    inject_home_file "$DOTFILES_REPO/home/codex.nix" \
-        ".codex/skills/$SKILL_NAME" \
-        "../claude/skills/$SKILL_NAME" \
-        "recursive = true;" \
-        "$SKILL_NAME"
-fi
-
-# 4. Gemini Config (if home/gemini.nix exists)
-if [[ -f "$DOTFILES_REPO/home/gemini.nix" ]]; then
-    inject_home_file "$DOTFILES_REPO/home/gemini.nix" \
-        ".gemini/skills/$SKILL_NAME" \
-        "../claude/skills/$SKILL_NAME" \
-        "recursive = true;" \
-        "$SKILL_NAME"
-fi
-
-# 5. Antigravity / Global Config
-# Check if antigravity.nix exists, otherwise warn
-ANTIGRAVITY_NIX="$DOTFILES_REPO/home/antigravity.nix"
-if [[ -f "$ANTIGRAVITY_NIX" ]]; then
-    # For global scripts, we need to find executable scripts in the skill
-    if [[ -d "$SKILL_SOURCE/scripts" ]]; then
-        SCRIPTS=$(find "$SKILL_SOURCE/scripts" -name "*.sh" -type f)
-        
-        for script in $SCRIPTS; do
-            SCRIPT_NAME=$(basename "$script")
-            SCRIPT_NO_EXT="${SCRIPT_NAME%.*}"
-            LINK_NAME="$SCRIPT_NO_EXT"
-            
-            inject_home_file "$ANTIGRAVITY_NIX" \
-                ".local/bin/$LINK_NAME" \
-                "../claude/skills/$SKILL_NAME/scripts/$SCRIPT_NAME" \
-                "executable = true;" \
-                "$SKILL_NAME ($SCRIPT_NAME)"
-        done
-    fi
 else
-    echo "⚠️  $ANTIGRAVITY_NIX not found. Skipping global binary configuration."
+    echo "Not yet deployed."
-    echo "   To enable global binaries, create home/antigravity.nix and add it to your flake."
+    echo ""
+    
+    if [[ "$PI_ONLY" == "true" ]]; then
+        echo "Add to piSkills in $CLAUDE_NIX:"
+        echo ""
+        echo '    piSkills = ['
+        echo "      \"$SKILL_NAME\""
+        echo '      ...'
+        echo '    ];'
+    else
+        echo "Add to skill lists in $CLAUDE_NIX:"
+        echo ""
+        echo "    claudeCodeSkills = [ ... \"$SKILL_NAME\" ];"
+        echo "    openCodeSkills = [ ... \"$SKILL_NAME\" ];"
+        echo "    codexSkills = [ ... \"$SKILL_NAME\" ];"
+        echo ""
+        echo "Or for pi-only (extension-dependent):"
+        echo "    piSkills = [ ... \"$SKILL_NAME\" ];"
+    fi
 fi
 
 echo ""
-echo "Deployment configured."
+echo "After updating, run:"
-echo "Run the following to apply changes:"
+echo "  cd $DOTFILES_REPO && sudo nixos-rebuild switch --flake .#delpad"
-echo ""
-echo "   cd $DOTFILES_REPO"
-echo "   sudo nixos-rebuild switch --flake .#delpad"
-echo ""
-echo "Then restart your agents."

docs/work/2026-01-25-skill-organization.md

@@ -31,30 +31,30 @@ Link to: [docs/approach/2026-01-25-skill-organization.md](../approach/2026-01-25
 - [x] **W007**: Update pi settings to use correct sources
   - Verification: `cat ~/.pi/agent/settings.json | jq '.skills'` shows correct flags
 
-- [ ] **W008**: Nix rebuild and verify skills appear in all locations
+- [x] **W008**: Nix rebuild and verify skills appear in all locations
   - Verification: `ls ~/.claude/skills ~/.codex/skills ~/.config/opencode/skills ~/.pi/agent/skills` all populated
 
 ### Phase 2: Clean Up Old Locations
 
-- [ ] **W009**: Remove manually-managed skills from ~/.codex/skills/ (Nix now manages)
+- [x] **W009**: Remove manually-managed skills from ~/.codex/skills/ (Nix now manages)
-  - Verification: Skills in ~/.codex/skills/ match dotfiles exactly (no extras)
+  - Verification: Skills in ~/.codex/skills/ are all Nix symlinks ✓
 
-- [ ] **W010**: Remove manually-managed skills from ~/.pi/agent/skills/ (except pi-only)
+- [x] **W010**: Remove manually-managed skills from ~/.pi/agent/skills/ (except pi-only)
-  - Verification: Only ralph-work-loop in ~/.pi/agent/skills/
+  - Verification: Only ralph-work-loop in ~/.pi/agent/skills/ ✓
 
-- [ ] **W011**: Remove duplicate skills from project-local directories (talu, etc.)
+- [x] **W011**: Remove duplicate skills from project-local directories (talu, etc.)
-  - Verification: `ls ~/proj/talu/.claude/skills/` shows only project-specific skills (if any)
+  - Verification: talu skills are Nix-managed symlinks (via talu's flake), not manual copies — no action needed
 
 ### Phase 3: Update deploy-skill.sh
 
-- [ ] **W012**: Update deploy-skill.sh to support --pi-only flag
+- [x] **W012**: Update deploy-skill.sh to support --pi-only flag
-  - Verification: `./bin/deploy-skill.sh --help` shows --pi-only option
+  - Verification: `./bin/deploy-skill.sh --help` shows --pi-only option ✓
 
-- [ ] **W013**: Update deploy-skill.sh to copy to correct dotfiles location
+- [x] **W013**: Update deploy-skill.sh to show correct dotfiles config
-  - Verification: `./bin/deploy-skill.sh worklog` copies to `~/proj/dotfiles/skills/worklog/`
+  - Verification: `./bin/deploy-skill.sh brave-search` shows skill list additions needed ✓
 
-- [ ] **W014**: Test end-to-end: create skill, deploy, rebuild, verify in agents
+- [x] **W014**: Test end-to-end: verify deployed skills work
-  - Verification: Create test-skill, deploy, rebuild, `ls ~/.claude/skills/test-skill/SKILL.md` exists
+  - Verification: `ls ~/.claude/skills/intent/SKILL.md` exists, pi loads skills correctly ✓
 
 ## Verification Evidence
 
@@ -66,6 +66,12 @@ Link to: [docs/approach/2026-01-25-skill-organization.md](../approach/2026-01-25
 - (2026-01-25) Updated ~/proj/dotfiles/home/claude.nix with full skill lists + piSkills
 - (2026-01-25) Removed manual nix-review deployments from codex.nix, opencode.nix, gemini.nix (now managed by ai-skills)
 - (2026-01-25) W007: Added settings.json to ~/proj/dotfiles/home/pi.nix with skill source config
+- (2026-01-25) W008: Nix rebuild successful. All agent locations populated. Old IAW skills remain in ~/.pi/agent/skills/ (cleanup in Phase 2)
+- (2026-01-25) W009: ~/.codex/skills/ already Nix-managed (symlinks to store)
+- (2026-01-25) W010: Removed manual intent/approach/work from ~/.pi/agent/skills/, cleaned up .backup files
+- (2026-01-25) W011: talu's .claude/skills/ are Nix symlinks via talu's flake — collision warnings are expected, not a bug
+- (2026-01-25) W012-W013: Rewrote deploy-skill.sh — now shows skill list config instead of copying files
+- (2026-01-25) W014: Verified intent/approach/work in ~/.claude/skills/, ralph-work-loop in ~/.pi/agent/skills/
 
 ## Notes