SKILL.md
Scratchpad
Disposable code and artifacts live in .scratch/, either in the working directory or under a designated output directory. Never committed.
Smoke Tests
Any disposable code used to quickly verify something works. Write them liberally after implementing changes.
| Type | When to use | Example |
|---|---|---|
| Logic verification | Verify guard patterns, state machines, edge cases | vitest test asserting a staleness guard rejects stale responses |
| API/endpoint probes | Verify endpoints respond correctly | curl scripts hitting local dev server |
| Integration checks | Verify two systems work together | Script that creates a resource then reads it back |
| Regression probes | Verify a specific bug is fixed | Minimal repro of the bug, now passing |
- Promote to committed unit tests when a smoke test catches a real issue
Rules
- Write scratch code to
.scratch/— never commit it - Do not store secrets or raw tokens (
.envvalues, JWTs, API keys, cookies) - Check project instruction files (
CLAUDE.mdorAGENTS.md) for auth token scripts and API base URL - Name files descriptively:
{feature}-{what}.test.tsor{endpoint}.sh - Use the project's existing test runner (vitest, jest, etc.) for logic smoke tests
Notes
Write markdown notes as you work — findings, decisions, progress. Notes persist on disk across context clears.
Use the co-located script:
# Write a quick note (auto-named with timestamp)
scripts/scratch.sh write --tag research -p "Found that X uses Y pattern"
# Write from stdin
echo "curl returned 200" | scripts/scratch.sh write --tag probe
# Explicit file path within session
scripts/scratch.sh write my-test.sh -p "#!/bin/bash\necho test"
# List notes from current session
scripts/scratch.sh list
# Read latest note
scripts/scratch.sh read @latest
# List all sessions
scripts/scratch.sh list --allWhen run via run-agent, session defaults to the run ID. Standalone, pass --session or let it auto-bucket by date.