Files & workspace

Asset management

Placement, naming, versioning, ledger, archive — and an audit that finds the mess.

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

Background

Goal: be able to answer three questions at any time — which copy is the current version? how much was spent? which assets are reusable?

Why it is built this way

The order is placement, naming, versioning, ledger, archiving, and it cannot be reshuffled: naming needs a target directory before the name can be written, and a ledger row needs a stable file name before it can point at anything. The six classes assets_audit.py reports follow that same order, from a same-prefix pile-up to a hard naming defect. Exit code 1 turns 'the files are messy' into a number a step can refuse to pass.

Three ledgers exist because one question cannot pay for another: cost_ledger.json answers what was spent, asset_index.md answers what can be reused, provenance.csv answers whether the asset may ship. A version goes into the file name and never into the directory name, otherwise each version takes its own directory and the current copy still needs sorting to find. Old versions move into _deprecated/, because a measured cleanup in the default cwd cost 21 projects their evidence.

Where it bites

• Three versions of one file The naming rule bans expressing state through suffixes like -fixed or -submit-package, because those suffixes cannot be sorted and cannot name the current copy. One project reached 249 version files this way. assets_audit.py reports a same-prefix pile-up as one of its six classes, and exit code 1 stops the wrap-up step.
• A version number inside a directory name A copy named preview_v12 sits in a folder called preview_v12, and the next copy needs a folder of its own. Disk use doubles and the folder list stops reading as one project. The naming gate forbids a version in the directory name; a scan of 1270 files reported this class together with a missing cost ledger.
• The deliverable that never left the default cwd Work done under Documents/Codex in a date folder looks finished and is invisible the moment that folder gets cleaned. The placement gate keeps deliverables inside the project tree, and --default-cwd exists to list leftovers; a past cleanup in the default cwd removed the evidence of 21 projects.
• An asset nobody can license Files stored without the same-named json metadata leave the prompt, the source and the licence unknown, so the asset cannot be reused and cannot enter a delivery. provenance.csv is the ledger for that question, and gate five keeps unknown-licence assets out; a missing ledger fails the audit before the delivery counts as complete.

Inside this skill

1. 0. Positioning and boundaries
2. 1. Five-step workflow (details in `references/02-five-step-workflow.md`)
3. 2. Audit (turning "messy files" into something measurable)
4. 3. Hard gates (five)
5. 4. Anti-patterns
6. 5. Sources
7. Working discipline (three hard rules, **read before changing anything**)

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

When to use it

Asset and file management workflow: placement → naming → versioning → ledger → archiving, including an executable audit (version pile-up / semantic suffixes / version numbers inside directory names / missing cost ledger / leftovers in the default cwd). Used to answer three questions: which copy is the current version? how much was spent? which assets are reusable? Use when the user asks to save / archive / tidy files, wants a naming convention, version management or asset reuse, says the files are too messy, asks where to store something, asks to clean up files, or asks whether a copy is the final version.

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 asset-management.
3. Start a message with the trigger from the description, or name the skill directly.