Working in Scratch Areas
Overview
Helps Claude save one-off scripts and documents to persistent scratch areas instead of littering repositories with temporary files or using /tmp.
Core principles:
- Temporary work deserves permanent storage
- Scripts and documents should be documented, organized, and preserved
- Never use
/tmpor projecttmp/directories for these files - Files belong in
.scratch/subdirectories with context
Announce at start: "I'm using the working-in-scratch-areas skill."
When to Use
Use this skill when creating:
- One-off debug scripts
- Analysis or investigation tools
- Temporary documentation or reports
- Quick test scripts
- Data extraction utilities
- Monitoring or diagnostic tools
Don't use for:
- Production code that belongs in the main codebase
- Configuration files that should be committed
- Tests that belong in the test suite
- Documentation that should be in docs/
NEVER use /tmp or project tmp/ directories. Always use .scratch/ for temporary work.
Setup Workflow
Check for Existing Scratch Area
First, check if a scratch area already exists:
test -L .scratch && echo "Scratch area exists" || echo "No scratch area"
If the symlink exists, verify gitignore is configured (see below), then you're ready to use it.
Setting Up New Scratch Area
When no scratch area exists:
- Detect: "I notice this repository doesn't have a scratch area set up."
- Check CLAUDE.md: Check if scratch areas location is configured in
~/.claude/CLAUDE.md - If not configured: Ask user where they want scratch areas with AskUserQuestion tool
- Run setup script with the chosen location
- Optionally save the location to CLAUDE.md for future use
Setup Steps:
# 1. Get repo root
git rev-parse --show-toplevel
# Output: /Users/josh/workspace/some-repo
# 2. Check if configured in CLAUDE.md
grep -i "scratch areas:" ~/.claude/CLAUDE.md
# 3a. If configured, run setup (reads from CLAUDE.md automatically)
cd /Users/josh/workspace/some-repo && ~/.claude/skills/working-in-scratch-areas/scripts/setup-scratch-area.sh
# 3b. If not configured, ask user for location and run with --areas-root
cd /Users/josh/workspace/some-repo && ~/.claude/skills/working-in-scratch-areas/scripts/setup-scratch-area.sh --areas-root ~/workspace/scratch-areas
# 3c. If user wants to save preference, add --save-to-claude-md flag
cd /Users/josh/workspace/some-repo && ~/.claude/skills/working-in-scratch-areas/scripts/setup-scratch-area.sh --areas-root ~/workspace/scratch-areas --save-to-claude-md
# 4. Verify gitignore (see Gitignore Setup section below)
What the script does:
- Checks
~/.claude/CLAUDE.mdfor configured scratch areas location (or accepts --areas-root flag) - Creates scratch areas root directory and repository-specific subdirectory
- Creates symlink
{repo-root}/.scratch→ scratch area - Creates README from template with repository-specific information
- Optionally saves location to CLAUDE.md with --save-to-claude-md flag
Script Location: ~/.claude/skills/working-in-scratch-areas/scripts/setup-scratch-area.sh
Script Options:
--areas-root PATH- Specify scratch areas root directory (required if not in CLAUDE.md)--save-to-claude-md- Save the areas root to ~/.claude/CLAUDE.md for future use--help- Show help message
Configuring Scratch Areas Location
The setup script checks ~/.claude/CLAUDE.md for your preferred scratch areas location. If not found, you must provide --areas-root flag.
To configure in CLAUDE.md, add:
## Scratch Areas
When using the `dev-tools:working-in-scratch-areas` skill, create scratch areas in `~/workspace/scratch-areas` directory.
Suggested locations to offer user:
~/workspace/scratch-areas- Central location for all scratch areas~/workspace/pickled-scratch-area/areas- If using the full pickled-scratch-area repository$(dirname "$REPO_ROOT")/scratch-areas- Sibling to current repository (for project-specific scratch areas)
Use AskUserQuestion to present these options when not configured.
Gitignore Setup
After creating scratch area, ensure .scratch is gitignored:
Preferred: Global gitignore
# Check if globally ignored
git config --global core.excludesfile
# Verify .scratch is in that file
# If not set up, add to global gitignore
echo ".scratch" >> ~/.gitignore
git config --global core.excludesfile ~/.gitignore
Alternative: Project .gitignore
If global gitignore isn't used:
# Add to project .gitignore if not present
grep -q "^\.scratch$" .gitignore || echo ".scratch" >> .gitignore
Why global is preferred: Prevents accidental commits across all repositories.
Subdirectory Organization
Always Use Subdirectories
Organize scratch files into topic-specific subdirectories:
.scratch/
├── database-debug/
│ ├── README.md
│ ├── check-connections.sh
│ └── query-results.txt
├── performance-analysis/
│ ├── README.md
│ ├── profile-api.sh
│ └── results-2024-11-05.md
└── data-extraction/
├── README.md
└── extract-users.rb
Do NOT create files directly in .scratch/ root. Always use a subdirectory.
Subdirectory Workflow
-
Check for existing relevant subdirectory:
ls -la .scratch/ -
If relevant subdirectory exists: Ask user if it makes sense to use it:
- "I see there's already a
.scratch/database-debug/directory. Should I add this script there, or create a new subdirectory?"
- "I see there's already a
-
If creating new subdirectory:
- Use descriptive names:
database-debug,api-performance,user-data-extraction - Create a README.md explaining the purpose
- Use descriptive names:
-
Subdirectory README required: Every subdirectory MUST have a README.md describing:
- What kind of files are stored here
- What problem/investigation spawned these files
- How files relate to each other (if at all)
Example subdirectory README:
# Database Connection Debugging
## Purpose
Scripts and notes for investigating database connection timeout issues reported on 2024-11-05.
## Files
- `check-connections.sh` - Monitor active connections
- `query-slow-queries.sql` - Identify slow queries
- `findings.md` - Investigation notes and conclusions
## Status
Investigation completed 2024-11-08. Issue was connection pool exhaustion.
Keeping files for reference.
Script Creation Rules
When creating scripts in scratch areas, follow these mandatory rules:
1. Always Use Proper Shebang
Every script MUST start with #!/usr/bin/env <command>:
#!/usr/bin/env bash
#!/usr/bin/env python3
#!/usr/bin/env ruby
#!/usr/bin/env node
Why: Enables proper allow list management and makes scripts directly executable.
2. Make Scripts Executable
After creating a script (file with shebang), use the helper script to make it executable:
~/.claude/skills/working-in-scratch-areas/scripts/make-executable .scratch/subdir/script.sh
Why:
- Allows calling scripts directly (
./script.sh) instead of through interpreter - Helper script gets approved once, not per-file
- Consistent executable permissions
- Validates shebang exists (prevents making non-script files executable)
Never use chmod +x directly - use the helper script instead.
Important: Only make script files executable (files with shebangs). Do NOT make markdown files, text files, or other non-script files executable. The helper script will reject files without shebangs.
3. Call Scripts Directly
When invoking scripts, use direct execution:
✅ CORRECT:
./.scratch/database-debug/check-connections.sh
❌ WRONG:
bash .scratch/database-debug/check-connections.sh # Don't use interpreter
ruby .scratch/data-extraction/extract-users.rb # Don't use interpreter
Why: Direct execution