skill-isolation-tester

name

skill-isolation-tester

description

Use PROACTIVELY when validating Claude Code skills before sharing or public release. Automated testing framework using multiple isolation environments (git worktree, Docker containers, VMs) to catch environment-specific bugs, hidden dependencies, and cleanup issues. Includes production-ready test templates and risk-based mode auto-detection. Not for functional testing of skill logic or non-skill code.

Skill Isolation Tester

Tests Claude Code skills in isolated environments to ensure they work correctly without dependencies on your local setup.

When to Use

Trigger Phrases:

• "test skill [name] in isolation"
• "validate skill [name] in clean environment"
• "test my new skill in worktree/docker/vm"
• "check if skill [name] has hidden dependencies"

Use Cases:

• Test before committing or sharing publicly
• Validate no hidden dependencies on local environment
• Verify cleanup behavior (no leftover files/processes)
• Catch environment-specific bugs

Quick Decision Matrix

Request	Mode	Isolation Level
"test in worktree"	Git Worktree	Fast, lightweight
"test in docker"	Docker	Full OS isolation
"test in vm"	VM	Complete isolation
"test skill X" (unspecified)	Auto-detect	Based on skill risk

Risk-Based Auto-Detection

Risk Level	Criteria	Recommended Mode
Low	Read-only, no system commands	Git Worktree
Medium	File creation, bash commands	Docker
High	System config changes, VM ops	VM

Mode 1: Git Worktree (Fast)

Best for: Low-risk skills, quick iteration

Process:

1. Create isolated git worktree
2. Install Claude Code
3. Copy skill and run tests
4. Cleanup

Workflow: modes/mode1-git-worktree.md

Mode 2: Docker Container (Balanced)

Best for: Medium-risk skills, full OS isolation

Process:

1. Build/pull Docker image
2. Create container with Claude Code
3. Run skill tests with monitoring
4. Cleanup container and images

Workflow: modes/mode2-docker.md

Mode 3: VM (Safest)

Best for: High-risk skills, untrusted code

Process:

1. Provision VM, take snapshot
2. Install Claude Code
3. Run tests with full monitoring
4. Rollback or cleanup

Workflow: modes/mode3-vm.md

Test Templates

Production-ready templates in test-templates/:

Template	Use For
docker-skill-test.sh	Docker container/image skills
docker-skill-test-json.sh	CI/CD with JSON/JUnit output
api-skill-test.sh	HTTP/API calling skills
file-manipulation-skill-test.sh	File modification skills
git-skill-test.sh	Git operation skills

Usage:

chmod +x test-templates/docker-skill-test.sh
./test-templates/docker-skill-test.sh my-skill-name

# CI/CD with JSON output
export JSON_ENABLED=true
./test-templates/docker-skill-test-json.sh my-skill-name

Helper Library

lib/docker-helpers.sh provides robust Docker testing utilities:

source ~/.claude/skills/skill-isolation-tester/lib/docker-helpers.sh

trap cleanup_on_exit EXIT
preflight_check_docker || exit 1
safe_docker_build "Dockerfile" "skill-test:my-skill"
safe_docker_run "skill-test:my-skill" bash -c "echo 'Testing...'"

Functions: validate_shell_command, retry_docker_command, cleanup_on_exit, preflight_check_docker, safe_docker_build, safe_docker_run

Validation Checks

Execution:

• Skill completes without errors
• Output matches expected format
• Execution time acceptable

Side Effects:

• No orphaned processes
• Temporary files cleaned up
• No unexpected system modifications

Portability:

• No hardcoded paths
• All dependencies documented
• Works in clean environment

Test Report Format

# Skill Isolation Test Report: [skill-name]
## Environment: [Git Worktree / Docker / VM]
## Status: [PASS / FAIL / WARNING]

### Execution Results
✅ Skill completed successfully

### Side Effects Detected
⚠️ 3 temporary files not cleaned up

### Dependency Analysis
📦 Required: jq, git

### Overall Grade: B (READY with minor fixes)

Reference Materials

• modes/mode1-git-worktree.md - Fast isolation workflow
• modes/mode2-docker.md - Container isolation workflow
• modes/mode3-vm.md - Full VM isolation workflow
• data/risk-assessment.md - Skill risk evaluation
• data/side-effect-checklist.md - Side effect validation
• templates/test-report.md - Report template
• test-templates/README.md - Template documentation

Quick Commands

# Test with auto-detection
test skill my-new-skill in isolation

# Test in specific environment
test skill my-new-skill in worktree  # Fast
test skill my-new-skill in docker    # Balanced
test skill my-new-skill in vm        # Safest

---

Version: 0.1.0 | Author: Connor