zhongwei/gh-cskiro-claudex-meta-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:16:56 +08:00
commit 8a3d331e04
61 changed files with 11808 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

292
skills/skill-isolation-tester/modes/mode1-git-worktree.md Normal file
View File

@@ -0,0 +1,292 @@
# 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
```bash
# 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:**
```bash
BRANCH_NAME="test-skill-$(date +%s)" # e.g., test-skill-1699876543
```
**Create worktree:**
```bash
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
```bash
# 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:**
```bash
ls -la "$WORKTREE_PATH/.claude/skills/[skill-name]/"
```
### Step 4: Setup Development Environment
**Install dependencies if needed:**
```bash
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):**
```bash
# Only if skill needs .env for testing
cp ../.env "$WORKTREE_PATH/.env"
```
### Step 5: Take "Before" Snapshot
```bash
# 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:**
```bash
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
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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
```bash
# 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.