From scratch
Understand an existing project by playing with its real modules in a safe workspace. Creates a .scratch/ folder with runnable scripts that exercise key primitives and subsystems. Use when the user wants to build a mental model of a codebase through hands-on code — not for evaluating external libraries for adoption (use the `try` skill for that).
How this skill is triggered — by the user, by Claude, or both
Slash command
/scratch:scratchThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are exploring an existing project the user wants to understand from the
You are exploring an existing project the user wants to understand from the inside. Your job is to create runnable scripts that walk through the project's key modules, revealing how they work through real execution rather than static reading.
This is for understanding something you already have — building a mental model
by touching real code in a safe, exploratory way. If the user wants to evaluate
something new for adoption, use the try skill instead.
The user will say something like:
scratch this projectscratch this project — focus on the auth systemhelp me understand how this codebase workswalk me through the internalshow does the payment module actually work?scratch around in the data pipelineThey may optionally provide:
WORKSPACE SETUP
───────────────
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ User asks to │ │ Confirm │ │ Create │
│ scratch │────>│ inside a │────>│ .scratch/ │
│ │ │ project │ │ workspace │
└──────────────┘ └──────────────┘ └──────────────┘
.scratch/ at the project root..scratch/ to .gitignore if not already present.Safety rule: .scratch/ scripts must NOT modify production code. They
import and exercise modules read-only. No writes to the project's database,
no mutations to config files, no side effects outside .scratch/.
Workspace structure:
<project-root>/
└── .scratch/
├── 01-<module>.{ts,py,js}
├── 02-<module>.{ts,py,js}
├── ...
├── 99-compose.{ts,py,js}
└── Tutorial.md
Goal: Identify the project's key primitives, modules, and subsystems.
DISTILL CHECK
─────────────
Is the distill skill available in this session?
YES → use it for a primitive inventory
NO → manual recon (see below)
If the distill skill is available (check the current host's available skills):
distill skill on the current project.If the distill skill is NOT available, perform manual reconnaissance:
RECON SEQUENCE
──────────────
Entry points → Package manifest → Source tree → Public API → Tests
Read in this order:
index.*.ls -R src/ | head -40 or equivalent.After recon, produce a mental inventory (hold it, don't write yet):
MODULES IDENTIFIED
──────────────────
1. <ModuleName> — what it does, one line
2. <ModuleName> — what it does, one line
...
N. <Connection> — how they wire together
If the user gave a specific angle ("how does caching work?"), filter to relevant modules. Otherwise, cover the top 5-8 most important ones.
Goal: One script per primitive or critical module boundary. Each is self-contained and runnable.
SCRIPT STRUCTURE
────────────────
┌─ .scratch/01-<name>.ts ─────────────────────────────┐
│ │
│ // MODULE: <Name> │
│ // WHAT: <one-line description> │
│ // EXPECT: <what should happen when you run it> │
│ // ENTRY POINT: <file:line in the real codebase> │
│ │
│ <import from the project's own modules> │
│ <exercise the module with clear inputs> │
│ <print/assert the result> │
│ │
│ // FINDINGS: │
│ // - <what you learned about how this works> │
│ // - <surprising internal behavior> │
│ // - <connections to other modules> │
│ │
└───────────────────────────────────────────────────────┘
Rules for exploration scripts:
file:line) in the real codebase for each module.
This tells the user where to start reading.After each script runs, update your mental model. Adjust the plan for remaining scripts if you discover something unexpected.
Goal: Wire 2-4 modules together to demonstrate a real workflow through the codebase.
.scratch/99-compose.ts
──────────────────────
// COMPOSITION: <what this demonstrates>
// MODULES USED: 01, 03, 05
// SCENARIO: <realistic workflow through the codebase>
This shows how the project's internals actually connect. The composition should trace a real user-facing operation end to end — for example, what happens when a request comes in, gets validated, hits the database, and returns a response.
If the user provided a specific scenario, question, or screenshot, the composition MUST target that. If not, trace the most representative end-to-end workflow that emerged from exploration.
Write .scratch/Tutorial.md. Structure:
# Understanding: <project-name>
> <one-line summary of the project's architecture>
## Architecture Overview
<2-3 sentences. What's the mental model? How do the pieces fit?>
## Key Modules
### 1. <Module Name>
<What it does. How it works internally. Entry point in the codebase
(file:line). Link to .scratch/01-*.>
### 2. <Module Name>
...
## How They Connect
<How modules wire together. Data flow. The critical path.
Link to .scratch/99-compose.>
## Surprises
<Bulleted list. Things you wouldn't guess from reading the code.
Hidden coupling. Implicit contracts. Non-obvious initialization order.>
## Dead Ends
<Things that didn't work. Failed approaches. Modules that looked
important but weren't. Misleading names. This section preserves
failure signal so the user doesn't repeat your dead ends.>
## Mental Model
<The compressed understanding. If you had to explain this codebase
to a new team member in 2 minutes, what would you say?>
Throughout all phases, follow this cadence:
LOOP (per script)
─────────────────
WRITE ──> RUN ──> OBSERVE ──> NOTE FINDINGS
^ │
└─────── ADJUST PLAN ─────────────┘
Before declaring done, verify:
✓ .scratch/ contains 3-8 numbered exploration scripts
✓ .scratch/99-compose.{ts,py} exists and runs
✓ Every script was actually executed
✓ Each script notes its entry point (file:line) in the real codebase
✓ No script modifies production code
✓ Tutorial.md exists in .scratch/ with all sections
✓ Surprises and Dead Ends sections capture non-obvious findings
✓ .scratch/ suggested for .gitignore
On first use in a session, silently check for a newer version:
https://raw.githubusercontent.com/abpai/skills/main/versions.json.scratch against this file's metadata.version.scratch update available (local {X.Y} → remote {A.B}). Would you like me to update it for you first? I can run
npx skills update scratchfor you.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub abpai/skills