# Scratchpad

> How to use the scratchpad tools (mechanics + etiquette + context discipline).

- Skill: `filmicgaze/scratchpad` (Agent Skill)
- Install (CLI): `npx skillmds@latest add filmicgaze/scratchpad`
- Raw SKILL.md: https://api.skillmd.com/api/skills/filmicgaze/scratchpad/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: filmicgaze (https://skillmd.com/u/filmicgaze)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/filmicgaze/scratchpad

---


This skill covers how to use the scratchpad tools (mechanics), basic etiquette, and how to avoid accidental context bloat.

Precedence:
– The system prompt overrides this skill.
– If another instruction explicitly specifies different scratchpad behaviour for the current task/profile, follow the more specific instruction; otherwise use this baseline for tool usage and safety.

What the scratchpad is:
- A shared workspace surface alongside the transcript (drafting, restructuring, whole-document work). Both the user and the assistant can see and edit its contents via the scratchpad UI.
- It persists across turns while the app is open, but does not survive app restarts. Don’t treat it as long-term profile memory.
- If something must persist beyond this app session, either (a) quote the relevant excerpt into chat, or (b) save it to a document explicitly.

Context discipline (why this matters):
- Context is a limited resource; treat it that way.
- Scratchpad text is not automatically in the model’s context.
- Tool outputs *are* in context. Large `scratchpad_get` calls or dumping the whole pad into chat will bloat context fast.
- Prefer navigation (`scratchpad_meta`, `scratchpad_find`) and small, targeted reads. Pull only what you need for the next step.

Default etiquette (defaults, not hard laws):
- Prefer to summarize and orient in chat (what changed, where to look) rather than re-streaming the full scratchpad contents the user can already see.
- Don’t paste the entire scratchpad into chat by default; it can bloat context and is usually redundant. Quote small, relevant snippets or show specific diffs when that clearly helps.
- Open/edit the scratchpad only when the user asks, or when it’s clearly the cleanest way to work (long text, restructuring, whole-document edits).
- Prefer reading before overwriting; do not silently erase. If clearing or replacing, say so briefly.
- When you’re asked to put an existing doc into the scratchpad for editing, use the actual content of that doc as the `scratchpad_set` text. Don’t substitute placeholders; the whole point is to have the working text there.
- Remember: the user can see and edit the scratchpad. Treat it as a joint workbench, not a private notebook.

Recommended flow (default):
1) Orient with `scratchpad_meta()` when you’re unsure of size or whether it changed.
2) Locate with `scratchpad_find(query, ...)` when you need a specific passage/heading.
3) Read minimally with `scratchpad_get(start=..., max_chars=...)` and page as needed.

When to ask “are you sure?” (gentle check):
- If the user asks to paste/echo the entire scratchpad into chat or to retrieve a very large chunk via `scratchpad_get`, mention that it may bloat context and is usually redundant with the scratchpad UI, and suggest:
  - quoting only the relevant section, or
  - keeping it in the scratchpad and working by headings/sections, or
  - saving to / editing via documents tools if it’s a stable file.

Writing and size limits:
- `scratchpad_set` / `scratchpad_append` may enforce a size cap. If a write fails due to the cap, say so and suggest reducing content or clearing first.

Allowed tools:
- scratchpad_open
- scratchpad_meta
- scratchpad_find
- scratchpad_get
- scratchpad_set
- scratchpad_append
- scratchpad_clear