Files & workspace

Workspace hygiene

Separate scratch from deliverables, so the folder you send is the folder you meant.

Free Free to read and free to ask for by email.

Background

Whether a file should stay is decided by "who opens it and when", not by how hard it was to make.

Files for your own reproduction go in work/; files the user takes away go in outputs/<date>-<topic>/; the two must never mix.

Scope: any agent that produces files in a session directory — Codex, Claude Code, DSH and the like. Session directories generated by the application (e.g. new-chat-3) must not be renamed — the path is how the application identifies the session; cleanliness happens inside the session (work/ and outputs/) and at the moment files are handed over.

Why it is built this way

A file is kept or dropped by who opens it and when, so the two zones are separated before any naming happens: work/ expires with the session and can be deleted wholesale, outputs/YYYYMMDD-topic/ is what the user keeps. The four questions run in order and all four must pass before a file enters outputs. Doubt goes back to work/. A process file can be rebuilt in minutes; a screenshot left in a delivery folder keeps costing the user every search after that.

Three segments are mandatory and three are added only when they remove a real ambiguity, which is why the ladder stops at the first hit: date, topic, type, then a sequence, then a channel or aspect qualifier, then -vN in the filename. Two tests decide whether the result works: send one file alone over WeChat and say which episode and spec it is, or put any two files side by side and tell them apart unopened. tidy_check.py only reads; exit code 0 is the finish line.

Where it bites

• Three finalcut.mp4 side by side Delivering one identically named file for several episodes leaves three finalcut.mp4 copies in a chat window, and nobody can say which is which. The naming ladder adds a sequence before anything else, and the out-of-folder test catches it: the file alone must still name its episode.
• Delivery files flat in the outputs root One session left 16 files lying in the outputs root, and finding the main file meant paging through them. The first gate allows only INDEX.md there, and tidy_check.py lists every loose file still around, so the wrap-up cannot end until the list is empty.
• A session nobody can find again Letting the application name a session new-chat-3 makes it unfindable by name later. One audit counted 33 of 61 sessions in that class, and only 10 of 35 delivery folders carried a date prefix. The skill fixes naming inside the session and leaves the session directory alone, because the path is how the application identifies the session.
• Work files burned into a delivery Screenshots, debug scripts, logs and extracted frames look like output and are not. Inside a delivery folder they make the user pick one file out of thirty. The fourth gate keeps work/ out of every delivery, and any doubtful answer in the four questions sends the file back there.

Inside this skill

1. 0. One-sentence principle
2. 1. Three zones
3. 2. The four delivery questions (decision gate)
4. 3. Naming formula (three mandatory segments + three on-demand segments)
5. 4. Action sequence for one delivery (3–5 minutes)
6. 5. Hard gates (five)
7. 6. Anti-patterns (measured on the workstation)
8. 7. Division of labour with other skills
9. 8. When you need the details

The outline is the skill file's own headings, in the order it uses them.

When to use it

Keep the session workspace clean: separate process files (safe to delete at any time) from delivery files (what the user takes away), put every delivery in an outputs/YYYYMMDD-topic-keyword/ folder (except WeChat Official Account / Xiaohongshu / Douyin assets, which go in the platform folders), name files to one convention, and maintain INDEX.md and 00-delivery-notes.md. Use when 'the files are a mess', 'tidy the folder', 'where do deliverables go', 'naming convention', 'clean up at the end', 'outputs is full of loose files', 'package it up and send it to the user'; not responsible for in-project version pile-up, cost accounting or licence accounting (that is asset-management).

How to use it

1. Ask for the file by email — it is a single SKILL.md.
2. Put it in the skills folder your agent reads, in a directory named workspace-hygiene.
3. Start a message with the trigger from the description, or name the skill directly.