gh-cskiro-claudex-meta-tools/skills/skill-isolation-tester/modes/mode1-git-worktree.md

Mode 1: Git Worktree Isolation

When to Use

Best for:

• Read-only skills or skills with minimal file operations
• Quick validation during development
• Skills that don't require system package installation
• Testing iterations where speed matters

Not suitable for:

• Skills that install system packages (npm install, apt-get, brew, etc.)
• Skills that modify system configurations
• Skills that require a clean Node.js environment

Risk Level: Low complexity skills only

Advantages

• ⚡ Fast: Creates worktree in seconds
• 💾 Efficient: Shares git history, minimal disk space
• 🔄 Repeatable: Easy to create, test, and destroy
• 🛠️ Familiar: Same git tools you already know

Limitations

• ❌ Shares system packages (node_modules, global npm packages)
• ❌ Shares environment variables and configs
• ❌ Same OS user and permissions
• ❌ Cannot test system-level dependencies
• ⚠️ Not true isolation - just a separate git checkout

Prerequisites

1. Must be in a git repository
2. Git worktree feature available (Git 2.5+)
3. Clean working directory (or willing to proceed with uncommitted changes)
4. Sufficient disk space for additional worktree

Workflow

Step 1: Validate Environment

# Check if in git repo
git rev-parse --is-inside-work-tree

# Check for uncommitted changes
git status --porcelain

# Get current repo name
basename $(git rev-parse --show-toplevel)

If dirty working directory → warn user but allow proceeding (isolation is separate)

Step 2: Create Isolation Worktree

Generate unique branch name:

BRANCH_NAME="test-skill-$(date +%s)"  # e.g., test-skill-1699876543

Create worktree:

WORKTREE_PATH="../$(basename $(pwd))-${BRANCH_NAME}"
git worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME"

Example result: /Users/connor/claude-test-skill-1699876543/

Step 3: Copy Skill to Worktree

# Copy skill directory to worktree's .claude/skills/
cp -r ~/.claude/skills/[skill-name] "$WORKTREE_PATH/.claude/skills/"

# Or if skill is in current repo
cp -r ./skills/[skill-name] "$WORKTREE_PATH/.claude/skills/"

Verify copy:

ls -la "$WORKTREE_PATH/.claude/skills/[skill-name]/"

Step 4: Setup Development Environment

Install dependencies if needed:

cd "$WORKTREE_PATH"

# Detect package manager
if [ -f "pnpm-lock.yaml" ]; then
  pnpm install
elif [ -f "yarn.lock" ]; then
  yarn install
elif [ -f "package-lock.json" ]; then
  npm install
fi

Copy environment files (optional):

# Only if skill needs .env for testing
cp ../.env "$WORKTREE_PATH/.env"

Step 5: Take "Before" Snapshot

# List all files in worktree
find "$WORKTREE_PATH" -type f > /tmp/before-files.txt

# List running processes (for comparison later)
ps aux > /tmp/before-processes.txt

# Current disk usage
du -sh "$WORKTREE_PATH" > /tmp/before-disk.txt

Step 6: Execute Skill in Worktree

Open new Claude Code session in worktree:

cd "$WORKTREE_PATH"
claude

Run skill with test trigger:

• User manually tests skill with trigger phrases
• OR: Use Claude CLI to run skill programmatically (if available)

Monitor execution:

• Watch for errors in output
• Note execution time
• Check resource usage

Step 7: Take "After" Snapshot

# List all files after execution
find "$WORKTREE_PATH" -type f > /tmp/after-files.txt

# Compare before/after
diff /tmp/before-files.txt /tmp/after-files.txt > /tmp/file-changes.txt

# Check for new processes
ps aux > /tmp/after-processes.txt
diff /tmp/before-processes.txt /tmp/after-processes.txt > /tmp/process-changes.txt

# Check disk usage
du -sh "$WORKTREE_PATH" > /tmp/after-disk.txt

Step 8: Analyze Results

Check for side effects:

# Files created
grep ">" /tmp/file-changes.txt | wc -l

# Files deleted
grep "<" /tmp/file-changes.txt | wc -l

# New processes (filter out expected ones)
# Look for processes related to skill

Validate cleanup:

# Check for leftover temp files
find "$WORKTREE_PATH" -name "*.tmp" -o -name "*.temp" -o -name ".cache"

# Check for orphaned processes
# Look for processes still running from skill

Step 9: Generate Report

Execution Results:

• ✅ Skill completed successfully / ❌ Skill failed with error
• ⏱️ Execution time: Xs
• 📊 Resource usage: XMB disk, X% CPU

Side Effects:

• Files created: [count] (list if < 10)
• Files modified: [count]
• Processes created: [count]
• Temporary files remaining: [count]

Dependency Analysis:

• Required tools: [list tools used by skill]
• Hardcoded paths: [list any absolute paths found]
• Environment variables: [list any ENV vars referenced]

Step 10: Cleanup

Ask user:

Test complete. Worktree location: $WORKTREE_PATH

Options:
1. Keep worktree for debugging
2. Remove worktree and branch
3. Remove worktree, keep branch

Your choice?

Cleanup commands:

# Option 2: Full cleanup
git worktree remove "$WORKTREE_PATH"
git branch -D "$BRANCH_NAME"

# Option 3: Keep branch
git worktree remove "$WORKTREE_PATH"

Interpreting Results

✅ PASS - Ready for git worktree environments

• Skill completed without errors
• No unexpected file modifications
• No orphaned processes
• No hardcoded paths detected
• Temporary files cleaned up

⚠️ WARNING - Works but has minor issues

• Skill works but left temporary files
• Uses some hardcoded paths (but non-critical)
• Performance could be improved
• Missing some documentation

❌ FAIL - Not ready

• Skill crashed or hung
• Requires system packages not installed
• Modifies files outside skill directory without permission
• Creates orphaned processes
• Has critical hardcoded paths

Common Issues

Issue: "Skill not found in Claude"

Cause: Skill wasn't copied to worktree's .claude/skills/ Fix: Verify copy command and path

Issue: "Permission denied" errors

Cause: Skill trying to write to protected directories Fix: Identify problematic paths, suggest using /tmp or skill directory

Issue: "Command not found"

Cause: Skill depends on system tool not installed Fix: Document dependency, suggest adding to skill README

Issue: Test results different from main directory

Cause: Different node_modules or configs Fix: This is expected - worktree shares some state, not true isolation

Best Practices

1. Always take before/after snapshots for accurate comparison
2. Test multiple times to ensure consistency
3. Check temp directories (/tmp, /var/tmp) for leftover files
4. Monitor processes for at least 30s after skill completes
5. Document all dependencies found during testing
6. Use relative paths in skill code, never absolute
7. Cleanup worktrees regularly to avoid clutter

Quick Command Reference

# Create test worktree
git worktree add ../test-branch -b test-branch

# List all worktrees
git worktree list

# Remove worktree
git worktree remove ../test-branch

# Remove worktree and branch
git worktree remove ../test-branch && git branch -D test-branch

# Find temp files created
find /tmp -name "*skill-name*" -mtime -1

---

Remember: Git worktree provides quick, lightweight isolation but is NOT true isolation. Use for low-risk skills or fast iteration during development. For skills that modify system state, use Docker or VM modes.