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)
This commit is contained in:
dan 2026-01-25 12:31:17 -08:00
parent 9ce4c83a17
commit b6b47f8b38
3 changed files with 92 additions and 210 deletions

View file

@ -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"}

View file

@ -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 niri-window-capture
$0 web-search # Deploy to all agents
$0 --pi-only ralph-work-loop # Deploy to pi only
This script:
1. Copies skill to dotfiles/claude/skills/
2. Shows you the Nix config to add
3. Reminds you to rebuild
1. Validates the skill exists in skills/
2. Checks if skill is in skills.nix registry
3. Shows which agent lists to update in dotfiles/home/claude.nix
You must manually:
- Edit home/claude.nix
- Edit home/opencode.nix
- Run: sudo nixos-rebuild switch --flake .#delpad
- Restart AI agents
Skills are sourced from this repo via Nix flake.
The ai-skills module deploys them to agent locations.
Available skills:
EOF
@ -37,88 +36,28 @@ EOF
exit 1
}
# Function to inject config into Nix file
inject_nix_config() {
local target_file="$1"
local config_block="$2"
local marker="$3" # Unique string to check if already deployed
if [[ ! -f "$target_file" ]]; then
echo "⚠️ File not found: $target_file (skipping)"
return
fi
if grep -q "$marker" "$target_file"; then
echo " Config already present in $(basename "$target_file")"
else
echo "Injecting config into $(basename "$target_file")..."
# 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"
}
# Parse arguments
while [[ $# -gt 0 ]]; do
case $1 in
--pi-only)
PI_ONLY=true
shift
;;
--help|-h)
usage
;;
*)
SKILL_NAME="$1"
shift
;;
esac
done
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
if [[ -d "$SKILL_DEST" ]]; then
echo "⚠️ Skill already deployed: $SKILL_DEST"
read -p "Overwrite? [y/N] " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
echo "Cancelled"
exit 1
fi
rm -rf "$SKILL_DEST"
# Check if in skills.nix registry
if ! grep -q "\"$SKILL_NAME\"" "$SKILLS_REPO/skills.nix" 2>/dev/null && \
! grep -q "^ $SKILL_NAME = " "$SKILLS_REPO/skills.nix" 2>/dev/null; then
echo "⚠️ Skill '$SKILL_NAME' not in skills.nix registry"
echo ""
echo "Add to skills.nix:"
echo " $SKILL_NAME = \"<description>\";"
echo ""
fi
# Check for security docs
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
"
# 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
echo "Deploying skill: $SKILL_NAME"
echo ""
echo "Skill: $SKILL_NAME"
echo "Source: $SKILL_SOURCE"
echo "Dest: $SKILL_DEST"
echo ""
# Copy skill
mkdir -p "$(dirname "$SKILL_DEST")"
cp -r "$SKILL_SOURCE" "$SKILL_DEST"
# Check if already deployed
in_claude=$(grep -c "\"$SKILL_NAME\"" "$CLAUDE_NIX" 2>/dev/null | grep -v "^0$" || true)
echo "✓ Skill copied to dotfiles"
echo ""
if [[ -n "$SECURITY_WARNING" ]]; then
echo "$SECURITY_WARNING"
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
if [[ -n "$in_claude" ]]; then
echo "✓ Already in deployment lists"
echo ""
echo "Current deployment:"
grep -B2 -A2 "\"$SKILL_NAME\"" "$CLAUDE_NIX" | head -20
else
echo "⚠️ $ANTIGRAVITY_NIX not found. Skipping global binary configuration."
echo " To enable global binaries, create home/antigravity.nix and add it to your flake."
echo "Not yet deployed."
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 "Run the following to apply changes:"
echo ""
echo " cd $DOTFILES_REPO"
echo " sudo nixos-rebuild switch --flake .#delpad"
echo ""
echo "Then restart your agents."
echo "After updating, run:"
echo " cd $DOTFILES_REPO && sudo nixos-rebuild switch --flake .#delpad"

View file

@ -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)
- Verification: Skills in ~/.codex/skills/ match dotfiles exactly (no extras)
- [x] **W009**: Remove manually-managed skills from ~/.codex/skills/ (Nix now manages)
- Verification: Skills in ~/.codex/skills/ are all Nix symlinks ✓
- [ ] **W010**: Remove manually-managed skills from ~/.pi/agent/skills/ (except pi-only)
- Verification: Only ralph-work-loop in ~/.pi/agent/skills/
- [x] **W010**: Remove manually-managed skills from ~/.pi/agent/skills/ (except pi-only)
- Verification: Only ralph-work-loop in ~/.pi/agent/skills/
- [ ] **W011**: Remove duplicate skills from project-local directories (talu, etc.)
- Verification: `ls ~/proj/talu/.claude/skills/` shows only project-specific skills (if any)
- [x] **W011**: Remove duplicate skills from project-local directories (talu, etc.)
- 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
- Verification: `./bin/deploy-skill.sh --help` shows --pi-only option
- [x] **W012**: Update deploy-skill.sh to support --pi-only flag
- Verification: `./bin/deploy-skill.sh --help` shows --pi-only option
- [ ] **W013**: Update deploy-skill.sh to copy to correct dotfiles location
- Verification: `./bin/deploy-skill.sh worklog` copies to `~/proj/dotfiles/skills/worklog/`
- [x] **W013**: Update deploy-skill.sh to show correct dotfiles config
- Verification: `./bin/deploy-skill.sh brave-search` shows skill list additions needed ✓
- [ ] **W014**: Test end-to-end: create skill, deploy, rebuild, verify in agents
- Verification: Create test-skill, deploy, rebuild, `ls ~/.claude/skills/test-skill/SKILL.md` exists
- [x] **W014**: Test end-to-end: verify deployed skills work
- 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